From e0cc8e39646c11e80a442fbd1c78a7669d087695 Mon Sep 17 00:00:00 2001 From: thegagne <1399002+thegagne@users.noreply.github.com> Date: Tue, 24 Mar 2026 13:43:31 -0500 Subject: [PATCH 1/4] fix(133,137): correct Create/Apply HTTP response codes to 201 Create should return 201 Created, not 200 OK, per RFC 7231. Apply should return 201 when creating and 200 when updating. The aep-2026 release incorrectly specified 200 for both; this corrects that with should-level guidance to allow backwards compatibility. Co-Authored-By: Claude Sonnet 4.6 --- aep/general/0133/aep.md.j2 | 10 +++++++++- aep/general/0137/aep.md.j2 | 12 +++++++++--- aep/general/example.oas.yaml | 24 ++++++++++++++++++------ 3 files changed, 36 insertions(+), 10 deletions(-) diff --git a/aep/general/0133/aep.md.j2 b/aep/general/0133/aep.md.j2 index ce0714b6..6791e8e2 100644 --- a/aep/general/0133/aep.md.j2 +++ b/aep/general/0133/aep.md.j2 @@ -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. - The response **must** be the resource itself. There is no separate response schema. @@ -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 diff --git a/aep/general/0137/aep.md.j2 b/aep/general/0137/aep.md.j2 index 684146d4..e85f7cc8 100644 --- a/aep/general/0137/aep.md.j2 +++ b/aep/general/0137/aep.md.j2 @@ -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 %} @@ -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 diff --git a/aep/general/example.oas.yaml b/aep/general/example.oas.yaml index e519e320..fb6a23ff 100644 --- a/aep/general/example.oas.yaml +++ b/aep/general/example.oas.yaml @@ -196,7 +196,7 @@ paths: $ref: '#/components/schemas/isbn' required: true responses: - '200': + '201': content: application/json: schema: @@ -269,7 +269,7 @@ paths: $ref: '#/components/schemas/publisher' required: true responses: - '200': + '201': content: application/json: schema: @@ -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 @@ -411,7 +417,7 @@ paths: $ref: '#/components/schemas/book' required: true responses: - '200': + '201': content: application/json: schema: @@ -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 @@ -579,7 +591,7 @@ paths: $ref: '#/components/schemas/book-edition' required: true responses: - '200': + '201': content: application/json: schema: From 2e66397e8d0fbbe1c51aaf4ac29886022eef874d Mon Sep 17 00:00:00 2001 From: thegagne <1399002+thegagne@users.noreply.github.com> Date: Tue, 24 Mar 2026 19:43:06 -0500 Subject: [PATCH 2/4] fix: remove RFC 7231 footnote links from notes --- aep/general/0133/aep.md.j2 | 3 +-- aep/general/0137/aep.md.j2 | 3 +-- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/aep/general/0133/aep.md.j2 b/aep/general/0133/aep.md.j2 index 6791e8e2..4b9e1694 100644 --- a/aep/general/0133/aep.md.j2 +++ b/aep/general/0133/aep.md.j2 @@ -96,7 +96,7 @@ Create methods implement a common request message pattern: **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 +code per RFC 7231. Implementations **should** accept `200` for backwards compatibility. - The response **must** be the resource itself. There is no separate response @@ -202,7 +202,6 @@ 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 diff --git a/aep/general/0137/aep.md.j2 b/aep/general/0137/aep.md.j2 index e85f7cc8..de2bed9c 100644 --- a/aep/general/0137/aep.md.j2 +++ b/aep/general/0137/aep.md.j2 @@ -115,7 +115,7 @@ Apply methods implement a common request message pattern: **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** +a resource is created, per RFC 7231. Implementations **should** accept `200` for backwards compatibility. {% endtabs %} @@ -164,5 +164,4 @@ 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 From 52d31de9cb2a6bede0620f56acb86d204cdeec97 Mon Sep 17 00:00:00 2001 From: thegagne <1399002+thegagne@users.noreply.github.com> Date: Tue, 24 Mar 2026 19:45:53 -0500 Subject: [PATCH 3/4] fix: remove notes, keep status code guidance only --- aep/general/0133/aep.md.j2 | 6 ------ aep/general/0137/aep.md.j2 | 5 ----- 2 files changed, 11 deletions(-) diff --git a/aep/general/0133/aep.md.j2 b/aep/general/0133/aep.md.j2 index 4b9e1694..b5b53499 100644 --- a/aep/general/0133/aep.md.j2 +++ b/aep/general/0133/aep.md.j2 @@ -93,12 +93,6 @@ Create methods implement a common request message pattern: {% 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. Implementations **should** accept `200` for -backwards compatibility. - - The response **must** be the resource itself. There is no separate response schema. - The response **should** include the fully-populated resource, and **must** diff --git a/aep/general/0137/aep.md.j2 b/aep/general/0137/aep.md.j2 index de2bed9c..2af0176a 100644 --- a/aep/general/0137/aep.md.j2 +++ b/aep/general/0137/aep.md.j2 @@ -113,11 +113,6 @@ Apply methods implement a common request message pattern: - 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. Implementations **should** -accept `200` for backwards compatibility. - {% endtabs %} ### Errors From 34582b0f5a475f372a96e7188b8fdc374c45c7d3 Mon Sep 17 00:00:00 2001 From: thegagne <1399002+thegagne@users.noreply.github.com> Date: Tue, 24 Mar 2026 19:46:48 -0500 Subject: [PATCH 4/4] fix: use must for 201 response code guidance --- aep/general/0133/aep.md.j2 | 2 +- aep/general/0137/aep.md.j2 | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/aep/general/0133/aep.md.j2 b/aep/general/0133/aep.md.j2 index b5b53499..126a1820 100644 --- a/aep/general/0133/aep.md.j2 +++ b/aep/general/0133/aep.md.j2 @@ -92,7 +92,7 @@ Create methods implement a common request message pattern: {% sample '../example.oas.yaml', '$.paths./publishers/{publisher_id}/books.post.responses.201' %} -- The response **should** return a `201 Created` HTTP status code. +- The response **must** return a `201 Created` HTTP status code. - The response **must** be the resource itself. There is no separate response schema. - The response **should** include the fully-populated resource, and **must** diff --git a/aep/general/0137/aep.md.j2 b/aep/general/0137/aep.md.j2 index 2af0176a..f0fae325 100644 --- a/aep/general/0137/aep.md.j2 +++ b/aep/general/0137/aep.md.j2 @@ -110,8 +110,8 @@ Apply methods implement a common request message pattern: {% sample '../example.oas.yaml', '$.paths./publishers/{publisher_id}/books/{book_id}.put.responses' %} -- 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. +- 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. {% endtabs %}