Reconfigure Content Negotiation to connect to the new API
Background
Content Negotiation is currently configured to conenct to localhosts on various machines in the datacenter. It needs to be reconfigured to talk to the new API.
Related context, but from before the cut-over to the new API. https://docs.google.com/document/d/1rR6mSESGfthLcXSAdC-cBhwVDH1tPA0qFXKQF80nb38/edit
How urgent
Definition of ready
-
Product owner: @ppolischuk1 -
Tech lead: @tpickard -
Service:: or C:: label applied -
Definition of done updated -
Acceptance testing plan: - Roll out change to
10.SERV/CROSSREF
to a test Handle prefix, probably 10.50505 (TODO). - Follow instructions in our own documentation to ensure it still performs as expected.
- Ask critical users (detailed below) to test against test DOI Handle server in the specified timeframe.
- Then cut over by updating the production DOI Handle server.
- Repeat steps following our own docs.
- Roll out change to
-
Weight applied
Definition of done
-
Available for acceptance testing via a staging URL, or otherwise -
Consider any impacts to current or future architecture/infrastructure, and update specifications and documentation as needed -
Public documentation reviewed and updated -
Acceptance criteria met -
All critical users of Content Negotiation warned about cut-over -
ORCID -
Status announcement -
Any other users contacted
-
-
Test Handle system updated to use new 10.SERV/CROSSREF
record, in collaboration with Robert at CNRI -
Production Handle system updated to use new 10.SERV/CROSSREF
record for content negotiation (see below).
-
-
Acceptance testing passed -
Deployed to production
Background - DOI, Content Negotiation, REST API
- Content Negotiation is a feature of HTTP in which a client sends an
Accepts
header and the server sends the most appropriate content representation. - DOI Content Negotiation is a feature of the DOI system, Crossref and other DOI Registration Agencies. When a request is sent to doi.org, the user is sent on a HTTP 302 redirect to the relevant DOI RA's content negotiation API. In the case of Crossref, this is on the
data.crossref.org
domain name.
Content Negotiation is currently handled by the Content Negotiation Proxy, which is a small service that implements HTTP content negotiation and then forwards requests to a specific REST API endpoint. This causes three issues:
- Extra 'hop', where it's not really needed.
- The
data.crossref.org
domain name is shared with other services, so we can't simply move that whole domain name. - The Content Negotiation Proxy doesn't have any connection to the REST API Pools (Public / Polite / Plus). This means that we can't offer the same pooling options for content negotiation, and therefore couldn't provide a SLA even if we wanted to.
The aim of this issue is to transfer DOI content negotiation to the new AWS-based REST API. To do this we need to configure the Handle server to point there. The REST API already supports content negotiation directly, so no changes are required in the Cayenne codebase. By configuring this direct connection to the REST API we address the the above issues:
- Remove the extra hop, which will improve performance.
- Separate out content negotiation from the other services running on
data.crossref.org
, simplifying our operations. - Allow Content Negotiation to be used under the same Pool semantics as the rest of our REST API.
10.SERV/CROSSREF Record
This is the configuration that determines how the DOI.org Handle server redirects Crossref DOIs for content negotiation. It is found at the DOI: https://doi.org/10.SERV/CROSSREF?type=10320/loc&noredirect.
Its current value is:
<locations http_sc="302">
<location weight="0" http_role="conneg" href_template="https://data.crossref.org/{hdl}" />
<xlocation weight="0" role="metadata" href_template="http://metadata.labs.crossref.org/?dois={hdl}&format=unixref" />
</locations>
It should be updated to:
<locations http_sc="302">
<location weight="0" http_role="conneg" href_template="https://api.crossref.org/v1/works/{hdl}/transform" />
</locations>
We don't support the xlocation
configuration, so it can be removed.
Sequence
- Roll out change to a test DOI Handle proxy. Acceptance test as above.
- Notify all high-impact users (as above) that we will make the switch, to give them notice (e.g. a grace period of 1 week) in case they are caching HTTP 302 redirects. This is only a courtesy; they shouldn't be.
- Roll out change to production DOI Handle proxy.
- Traffic should now be redirected to the
api.crossref.org
and not to thedata.crossref.org
. Users should not cache the HTTP 302 redirect, so the effect should be immediate. - After the grace period we can remove the service on
data.crossref.org
.