Ghost: Inconsistent response codes for "resource created" responses

[kevinansfield]

We have some inconsistency with the response codes returned for "resource created" responses. Some are returning 201 Created whereas others are returning 200 OK.

From my recent experience:

• POST /posts/ returns 201
• POST /webhooks/ returns 201
• POST /subscribers/ returns 200
• POST /invites/ returns 200

The response code is determined by the presence of a Location header, with the Location header being added on an ad-hoc basis which could be simplified as it's mostly duplication. Simplifying the logic of adding the header so that the default behaviour is applied for all non-special POST requests would also have effect of automating a 201 for any future resources.

After a little investigation it's been determined that the Location header is not used by Ghost-Admin, it was added for the original Backbone implementation of the admin area. If it's not used anywhere else we could probably remove all of the logic around the Location header and simply return 201 for all successful POST requests.

[ErisDS]

The only endpoint that I think would need a special case is /authentication/. There are quite a few POST routes there, and they don't all result in creation. e.g. POST /authentication/revoke/ but I assume they are POST requests to conform to oauth standards.

[hbogaeus]

Hey, I'm planning on fixing this issue and wish to get assigned to it.

[kevinansfield]

@hbogaeus adding your name here is enough 😄 Thanks for taking a look! If you run into any issues or need any help please check out the #contributing channel on our Slack team

[hbogaeus]

@kevinansfield Excellent, thanks!

[hbogaeus]

Hey @kevinansfield how should PUT requests be handled? Most (all?) of them result in creation (or the updating of a resource) and should thus respond with a 201?

[kirrg001]

@hbogaeus 200

[kirrg001]

After a little investigation it's been determined that the Location header is not used by Ghost-Admin, it was added for the original Backbone implementation of the admin area. If it's not used anywhere else we could probably remove all of the logic around the Location header and simply return 201 for all successful POST requests.

From https://tools.ietf.org/html/rfc7231#section-6.3.2

The primary resource created by the request is identified
by either a Location header field in the response or, if no Location
field is received, by the effective request URI.

That means to me, if we don't return the Location header, the request url identifies the created resource. So e.g. if you create a post, you trigger. POST /posts. This route does not identify the created resource. GET /posts is paginated and returns a bunch of posts (maybe not the created post).

I would like to keep the Location header for now and only concentrate on the correct status codes. Or let me know, if i am misunderstanding the RFC spec 👍

[kirrg001]

We will ensure resource creation is consistent in API v2, but not for v0.1.

We can also get rid of the location header in v2. If we want to add something similar in the future, we can do of course.

After a little investigation it's been determined that the Location header is not used by Ghost-Admin, it was added for the original Backbone implementation of the admin area. If it's not used anywhere else we could probably remove all of the logic around the Location header and simply return 201 for all successful POST requests.

[ErisDS]

I would advocate strongly for _not_ returning a post URL in the location header in v2. If we keep it, the location should be for the Content API resource URI, rather than the "front-end" location.

[kirrg001]

Closing this issue. API version V2 does not return the location header and it returns consistent status codes for adding + destroying resources.