Provide a mechanism for programmatic access to individual records

[datadavev]

Access to data records is currently available through the search API, but GEOME does not appear to provide a mechanism to directly retrieve a structured data representation of an individual record identifier (e.g. JSON-LD, JSON, or XML). For example, the identifier ark:/21547/lF2113 resolves to the URL https://geome-db.org/record/ark:/21547/lF2113. Retrieving the resource from that URL provides a HTML document that requires client side browser processing to render the result. Making the resource available as structured data would facilitate third party retrieval of the content and promote system interoperability.

There are three common approaches for advertising and supporting programmatic retrieval of structured data:

1. Custom URLs with a pattern to indicate the requested content type.

   For example, the application may provide a URL pattern that consistently provides a response in a particular content type given a URL pattern. So for example, the application may provide a URL like: https://geome-db.org/record/ark:/21547/lF2113.json to return a JSON representation of the content. Availability of such a URL can be provided through documentation of via a mechanism such as content negotiation or alternate references through Link headers (2 and 3 below).

2. Content negotiation by way of client specified Accept header.

   A client may include an Accept header with an expected content type in the request to retrieve the resource. For example:

   curl -H "Accept: application/json" "https://geome-db.org/record/ark:/21547/lF2113"

   The server would respond with a representation of the resource in the requested content type if such a rendering were available on the server. The response may also be a redirect to a URL such as that described in 1 above. There are many nuances to content negotiation, described in RFC 7321 section 5.3.2.

3. Content advertisement through Link response headers.

   An alternative to content negotiation gaining favor in linked open data approaches is for the resource provider to advertise availability of alternate forms of a resource through the Link header, RFC 8288. In particular, a rel type of alternate is used to indicate that the resource is available in a particular format from a particular URL (section 3.3). For example:

   Link: <https://geome-db.org/record/ark:/21547/lF2113.json>; rel="alternate"; type="application/json"

[jdeck88]

@datadavev : I looked again and there actually is a native JSON response, see:

https://api.geome-db.org/records/ark:/21547/lF2113?includeParent&includeChildren

See swagger docs at: https://api.geome-db.org/apidocs/#/Records

So, perhaps the easiest solution here is to add this header in the response?

Link: https://api.geome-db.org/records/ark:/21547/lF2113?includeParent&includeChildren; rel="alternate"; type="application/json"

[datadavev]

Nice. That should do just fine. Note that URIs need to be enclosed with <> so it would actually be:

Link: <https://api.geome-db.org/records/ark:/21547/lF2113?includeParent&includeChildren>; rel="alternate"; type="application/json"