edgio / hyperion Goto Github PK

1. Should @id values contain version numbers, and if so let's specify and update the examples.
2. Should resource names always be pluralized? If so let's specify explicitly.

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?

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:

1. No response body - not terribly useful
2. Full / partial resource returned - most clients don't use the resource returned here. In edge cases where a client needs the new resource, then can go back and GET it. This saves the API server (and developers) from having to re-query the state from the data store.
3. Hyperion 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"
        }
    }
}

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?

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"
}

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:

• POST new resource (a.k.a., "create")
• PUT to replace existing resource wholesale (a.k.a., "wholesale update")
• PATCH to update a subset of attributes of existing resource (a.k.a. "partial update")
• DELETE to remove an existing resource (a.k.a. "delete")
• GET ......

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.

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.

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.