thisissoon / api-specification Goto Github PK

For consistency as our APIs are camelCased I think query params should also be camelCased.

Example

/posts?ordering=published_on => /posts?ordering=publishedOn

We should add documentation about caching using ETag's and If-Match / If-None-Match headers.

Discuss @thisissoon/owners 😛

/orders/123 vs /orders/123/

I've just realised that our API spec doesn't have anything about OPTIONS method. The method can be used as an api descriptor which returns a valid data structure which is accepted by an endpoint.

OPTIONS /bla

Will return:

{
  "POST": {
    "description": "blabla",
    "parameters": {
      "title": {
        "type": "string",
        "description": "bla bla bla.",
        "required": true
      }
}

@krak3n @edwardoparearyee @peeklondon @jamesjwarren any thoughts?

Hey Guys

HMAC signing is going well so far but in our travels we have found there are some cases where HMAC signing request bodies for GET request results in you just signing an empty request body. This results in the same signature for those requests.

I was wondering if there was something unique we could always send and use has part of the signing / verification process, and we do already have something unique every request should have, a Correlation ID which is sent in the Correlation-ID header.

We could:

• Add the Correlation ID to the Client Secret Key
• Always send a request body (even for GET's that includes the Correlation ID) - This would mean sending the ID twice, once as part of the body and again as a header to check equality on the other side.

This would technically mean that every requests signature is unique.

Any thoughts?

We currently have a section in the spec which says POST, PUT and PATCH should always return an object representation of the created / updated object. This means it would be a HAL document.

We also then say that a 201 for POST should also return a Location header with the newly crated objects URI so the consumer can get the resource if needed.

So the question is this:

For POST should we return the object representation at all or should a POST return a 201 with the Location header and the object representation?