tschaffter
commented
2 months ago Architecture Draft
Responses
One approach I want to explore is to update the REST API to return JSON-LD responses (implementation at the backend level). The solution must be compatible with our specification-first development workflow. Another approach is to create the JSON-LD payload in the frontend app from JSON data received from the REST API (implementation at the frontend level).
Here, I want to explore the first approach so that even the data returned by the REST API benefit from additional context and are more accurately described.
First, JSON and JSON-LD has its own MIME type. They are also listed in these Common MIME types.
- application/json
- application/ld+json
The OpenAPI specification allows to specify different MIME types for the response format: https://swagger.io/docs/specification/adding-examples/
[!NOTE]
The OpenAPI 3.0 specification does not support the consumes and produces properties that were used in OpenAPI 2.0 (also known as Swagger 2.0). Instead, OpenAPI 3.0 introduced a new way of specifying the content types for request bodies and responses.
Example:
content:
application/xml:
schema:
$ref: '#/components/schemas/xml'
examples:
xml:
summary: A sample XML response
value: '<objects><object><id>1</id><name>new</name></object><object><id>2</id></object></objects>'
text/html:
schema:
type: string
examples:
html:
summary: A list containing two items
value: '<html><body><ul><li>item 1</li><li>item 2</li></ul></body></html>'[!WARNING]
It's not clear whether the OpenAPI generator supports OA specifications that define multiple MIME types for a given endpoint. See this ticket. If this feature is not supported, one solution would be to always return the response in JSON-LD format.
Requests
As a user of an API that supports multiple response MIME types, you can specify which format you want the API to return by setting the Accept header in your HTTP request. The Accept header tells the server which content types the client can process, and the server will respond with the appropriate content type if it supports it.
Here is an example of how you can specify the desired response format using the Accept header: cURL Example
If you want the response in JSON format:
curl -H "Accept: application/json" -X GET "https://api.example.com/example"If you want the response in XML format (assuming the API supports XML as well):
curl -H "Accept: application/xml" -X GET "https://api.example.com/example"To clarify:
- How to access this header information in the backend to identify the output format (JSON or JSON-LD).
- How to specify the format when using the OC API client for Angular
What product(s) is this feature for?
OpenChallenges
Description
As the product owner, I want SEs to understand the content of the challenge pages, so that they can be made more visible.
An initial JSON-LD schema for OC has now available (thanks @cconrad8 ): https://github.com/Sage-Bionetworks/core-models/blob/main/draft-data-models/challenges.jsonld
The goal of this ticket is to insert a
<script>element to the challenge page that includes the challenge data in JSON-LD format. Examples of such<script>elements is provided in the presentation Do Robots Dream of OpenChallenges?Anything else?
No response
Code of Conduct