Skip to content

fix(133,137): correct Create/Apply HTTP response codes to 201 #406

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
thegagne wants to merge 4 commits into
base: main
Choose a base branch
from
Open

fix(133,137): correct Create/Apply HTTP response codes to 201 #406

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e0cc8e3
fix(133,137): correct Create/Apply HTTP response codes to 201
thegagne Mar 24, 2026
2e66397
fix: remove RFC 7231 footnote links from notes
thegagne Mar 25, 2026
52d31de
fix: remove notes, keep status code guidance only
thegagne Mar 25, 2026
34582b0
fix: use must for 201 response code guidance
thegagne Mar 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion aep/general/0133/aep.md.j2
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,14 @@ Create methods implement a common request message pattern:

{% tab oas %}

{% sample '../example.oas.yaml', '$.paths./publishers/{publisher_id}/books.post.responses.200' %}
{% sample '../example.oas.yaml', '$.paths./publishers/{publisher_id}/books.post.responses.201' %}

- The response **should** return a `201 Created` HTTP status code.

**Note:** The aep-2026 release incorrectly specified `200 OK` for Create
responses. This guidance corrects that: `201 Created` is the appropriate status
code per [RFC 7231][rfc-7231]. Implementations **should** accept `200` for
backwards compatibility.

@toumorokoshi toumorokoshi Mar 24, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we should include this, as a convention it would litter the spec with a bunch of footnotes. remove?

@rambleraptor rambleraptor Mar 25, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The great thing about editions is that the old text lives in the aep-2026 branch.

It might be worth keeping a CHANGELOG of things we've changed, but we can also build that from git logs

@thegagne thegagne Mar 25, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed the note. It does clutter it so I agree with removing it, I just wanted to prompt all of us to think through how this could be a breaking change in some cases. While we can accept 200 for backward compatibility, new things being created would not necessarily know about that.

I'm not super worried about it at the moment, but this change could have implications for the lib, the linter, aepc, aepbase, etc., and anyone who uses them.

Our user base is not super large right now and so we can get away with making changes like these, which is nice. I think we just press forward, test things out, and fix them where we can.

@toumorokoshi toumorokoshi Mar 30, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good! the worst case scenario is we re-add it.


- The response **must** be the resource itself. There is no separate response
schema.
Expand Down Expand Up @@ -195,6 +202,7 @@ the ID of the newly-created resource.
Having a user-specified ID also means the client can precalculate the resource
path and use it in references from other resources.

[rfc-7231]: https://datatracker.ietf.org/doc/html/rfc7231#section-4.3.3
[data plane]: ./0111.md#data-plane
[errors]: ./0193
[field_behavior]: ./0203
Expand Down
12 changes: 9 additions & 3 deletions aep/general/0137/aep.md.j2
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,10 +108,15 @@ Apply methods implement a common request message pattern:

{% tab oas %}

{% sample '../example.oas.yaml', '$.paths./publishers/{publisher_id}/books/{book_id}.put.responses.200' %}
{% sample '../example.oas.yaml', '$.paths./publishers/{publisher_id}/books/{book_id}.put.responses' %}

- If the resource is created, the response **must** return a `201` status code.
- If the resource is updated, the response **must** return a `200` status code.
- If the resource is created, the response **should** return a `201` status code.
- If the resource is updated, the response **should** return a `200` status code.

**Note:** The aep-2026 release incorrectly specified `200 OK` for both cases.
This guidance corrects that: `201 Created` is the appropriate status code when
a resource is created, per [RFC 7231][rfc-7231]. Implementations **should**
accept `200` for backwards compatibility.

{% endtabs %}

Expand Down Expand Up @@ -159,4 +164,5 @@ See [AEP-134's patch and put](/134#patch-and-put) for more information.
- For ensuring idempotency in `Apply` methods, see [idempotency](/idempotency).
- For naming resources involving Unicode, see [unicode](/unicode).

[rfc-7231]: https://datatracker.ietf.org/doc/html/rfc7231#section-4.3.3
[strong consistency]: ./0121.md#strong-consistency
24 changes: 18 additions & 6 deletions aep/general/example.oas.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -196,7 +196,7 @@ paths:
$ref: '#/components/schemas/isbn'
required: true
responses:
'200':
'201':

@toumorokoshi toumorokoshi Mar 24, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

these examples are generated via aepc: https://github.com/aep-dev/aepc. It would be great to update that first. But I can do so after to align if that's too much effort.

@thegagne thegagne Mar 25, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll give it a shot.

@thegagne thegagne Mar 25, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

aep-dev/aep-lib-go#15 - I think this needs to happen first unless I'm mistaken?

@toumorokoshi toumorokoshi Mar 30, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yep! thanks for drafting that, and it's a go get to update aepc.

content:
application/json:
schema:
Expand Down Expand Up @@ -269,7 +269,7 @@ paths:
$ref: '#/components/schemas/publisher'
required: true
responses:
'200':
'201':
content:
application/json:
schema:
Expand Down Expand Up @@ -354,7 +354,13 @@ paths:
application/json:
schema:
$ref: '#/components/schemas/publisher'
description: Successful response
description: Successful response (updated)
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/publisher'
description: Successful response (created)
/publishers/{publisher_id}/books:
get:
description: List method for book
Expand Down Expand Up @@ -411,7 +417,7 @@ paths:
$ref: '#/components/schemas/book'
required: true
responses:
'200':
'201':
content:
application/json:
schema:
Expand Down Expand Up @@ -516,7 +522,13 @@ paths:
application/json:
schema:
$ref: '#/components/schemas/book'
description: Successful response
description: Successful response (updated)
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/book'
description: Successful response (created)
/publishers/{publisher_id}/books/{book_id}/editions:
get:
description: List method for book-edition
Expand Down Expand Up @@ -579,7 +591,7 @@ paths:
$ref: '#/components/schemas/book-edition'
required: true
responses:
'200':
'201':
content:
application/json:
schema:
Expand Down
Loading