edgio / hyperion Goto Github PK
View Code? Open in Web Editor NEWLightweight JSON specification from Edgecast
Home Page: https://edgio.github.io/hyperion
Lightweight JSON specification from Edgecast
Home Page: https://edgio.github.io/hyperion
Current spec requires any date time field in response to be in UTC timezone.
It's generally client's responsibility to format the date time field,
but, is there a use case that we want to allow users to ask for date time field in response in specific timezone?
Hyperion spec makes no mention of what type of response a 201 should be sending back. In order to reach some type consistency across all Hyperion compliant APIs there should be a standard in place for this.
According to the HTTP spec:
... a Location header field in the response or, if no Location field is received, by the effective request URI. The 201 response payload typically describes and links to the resource(s) created
According to Mozilla's dev site
The HTTP 201 Created success status response code indicates that the request has succeeded and ... the new resource is returned in the body of the message, its location being either the URL of the request, or the content of the
Location
header.
Both of those references have similarities but also some differences -- most notably the mention of what the body/payload should include. We should lean towards what former HTTP spec mentions however it does leave some room for interpretation using words like "typically describes" and not a MUST. The Location
header is common and should be part of the headers.
Given this, I see three possible avenues that an API can take. Return a Location
header along with:
LinkValue
to the new resource - While redundant with the HTTP specification, this appears to be the most Hyperion-esque. Not only do APIs benefit from not having to re-query, the response provides useful information about where the new resource is located.An example header + payload response for option 3 could be:
HTTP/1.1 201 Created
Date: Sun, 10 Nov 2021 23:26:07 GMT
Server: AWSGW Server...
Location: https://api.sample.com/apis/3d3f9275-a2bc-4fcc-be7b-a229f1d85ed3/specs/6e17e006-eddb-4c24-9618-94ad5d28c9b4
{
"@type": "NodeRef",
"@links" : {
"location": {
"href": "/apis/3d3f9275-a2bc-4fcc-be7b-a229f1d85ed3/specs/6e17e006-eddb-4c24-9618-94ad5d28c9b4",
"description": "A reference to the new API Specification"
}
}
}
An idea was floated during SSL Automation API review to have static / lookup endpoints be grouped under a path. Often 10+ endpoints that serve static lookup data for UIs to consume, might be nice to have a convention on grouping them in a way so they don't clutter up the service root path, leaving it for the more actionable endpoints.
I think there was a suggestion of /appendix
.
Please document the endpoint layouts, methods, status codes, and response content patterns for resource CRUD operations.
For example, these methods are used for the operations:
Document which status code should be used minimally for the successful cases (for example, 201 for PUT and 204 for DELETE).
Document when endpoint should return a body or not.
@id
values contain version numbers, and if so let's specify and update the examples.Should we define a spec for an API endpoint that responses Content-Disposition: attachment
header for downloadable contents?
Or should we separate out the endpoint as a download-only service?
If the endpoint can stay with the other Hyperion conforming endpoints, can the downloaded contents be not conforming to the spec?
It would be nice to provide a specific type for API devs that would like to provide an entry point to their APIs. This would be a default response with @links
and a few properties describing what the API is and where to learn more about it.
For example, APIs that version often use URL paths. But what happens if a client leaves out the URL path and hits the root? What should we return as a default response?
I'm proposing we return an object that provides links and few properties to describe the API. Something like the following:
{
"@type": "EntryPoint",
"@id": "/identity",
"@links": {
"v1": {
"href": "/identity/v1"
}
},
"name": "VDMS Identity Service API",
"description": "Some description about the API",
"documentation": "https://developer.vdms.io",
"support": "https://developer.vdms.io/support"
}
I propose we add code
to each ErrorDetail
object. Say you have a name attribute. It can fail for more than reason. For example, it has a required validation rule and a maximum character length validation rule. I'd like to define separate error messages for these on the frontend. In order to map an ErrorDetail
object to the specific error message defined on the frontend, I would need some kind of code like required_attribute
or invalid_length
. JSON:API supports this via a code
property: https://jsonapi.org/format/#error-objects
For example, if a client makes a request without name
, the response might look like this:
{
"@type": "Error",
"code": "invalid_request",
"title": "...",
"details": [
{
"@type": "ErrorDetail",
"description": "...",
"source": "/name",
"code": "required"
}
]
}
If a client makes a request with name
but it is too long, the response might look like this:
{
"@type": "Error",
"code": "invalid_request",
"title": "...",
"details": [
{
"@type": "ErrorDetail",
"description": "...",
"source": "/name",
"code": "too_long"
}
]
}
The frontend can then key off of required
or too_long
to display the proper error message defined on the frontend.
The alternative is for frontends to rely on description
provided by the backend.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.