diff --git a/aep/general/0135/aep.md.j2 b/aep/general/0135/aep.md.j2 index 6614ad78..27d1ef12 100644 --- a/aep/general/0135/aep.md.j2 +++ b/aep/general/0135/aep.md.j2 @@ -96,7 +96,7 @@ Delete methods implement a common request pattern: {% tab oas %} -{% sample '../example.oas.yaml', '$.paths./publishers/{publisher}/books/{book}.delete.responses.200' %} +{% sample '../example.oas.yaml', '$.paths./publishers/{publisher}/books/{book}.delete.responses.204' %} - Delete methods **should** return `204 No Content` with no response body. diff --git a/aep/general/0136/aep.md.j2 b/aep/general/0136/aep.md.j2 index fc4b315e..40e3a85f 100644 --- a/aep/general/0136/aep.md.j2 +++ b/aep/general/0136/aep.md.j2 @@ -26,14 +26,15 @@ apply consistently: - The HTTP URI **must** use a `:` character followed by the custom verb (`:archive` in the above example), and the verb in the URI **must** match the verb in the name of the RPC. - - If word separation is required, `camelCase` **must** be used. + - If word separation is required, `kebab-case` **must** be used. +- The name of the RPC **should** be a verb followed by a noun. + - The name of the RPC **must not** contain prepositions ("for", "with", + etc.). {% tab proto %} {% sample 'library.proto', 'rpc ArchiveBook' %} -- The name of the RPC **should** be a verb followed by a noun. - - The name **must not** contain prepositions ("for", "with", etc.). - The `body` clause in the `google.api.http` annotation **should** be `"*"`. - However, if using `GET` or `DELETE`, the `body` clause **must** be absent. - Custom methods **must** take a request message exactly matching the RPC name, @@ -45,11 +46,11 @@ apply consistently: {% tab oas %} -{% sample 'library.oas.yaml', '$.paths./publishers/{publisherId}/books/{bookId}:archive' %} - -- The name of the RPC **should** be a verb followed by a noun. - - The name of the RPC **must not** contain prepositions ("for", "with", - etc.). +```http +POST /v1/publishers/{publisher}/book/{book}:archive HTTP/2 +Host: bookstore.example.com +Accept: application/json +``` {% endtabs %} @@ -64,14 +65,14 @@ such: {% tab proto %} -{% sample 'library.proto', 'rpc ArchiveBook' %} +{% sample '../example.proto', 'rpc ArchivePublisher' %} - The parameter for the resource's path **must** be called `path`, and **must** be the only variable in the URI path. {% tab oas %} -**Note:** OAS example not yet written. +{% sample '../example.oas.yaml', '$.paths./publishers/{publisher}/books/{book}:archive' %} {% endtabs %} diff --git a/aep/general/example.oas.yaml b/aep/general/example.oas.yaml index eb0aedbb..75f077d4 100644 --- a/aep/general/example.oas.yaml +++ b/aep/general/example.oas.yaml @@ -1,13 +1,33 @@ { 'openapi': '3.1.0', 'servers': [{ 'url': 'http://localhost:8081' }], - 'info': { 'title': 'bookstore.example.com', 'version': 'version not set' }, + 'info': + { + 'title': 'bookstore.example.com', + 'description': 'An API for bookstore.example.com', + 'version': 'version not set', + }, 'paths': { '/isbns': { 'get': { + 'description': 'List method for isbn', + 'operationId': 'ListIsbn', + 'parameters': + [ + { + 'name': 'max_page_size', + 'in': 'query', + 'schema': { 'type': 'integer' }, + }, + { + 'name': 'page_token', + 'in': 'query', + 'schema': { 'type': 'string' }, + }, + ], 'responses': { '200': @@ -36,24 +56,11 @@ }, }, }, - 'parameters': - [ - { - 'in': 'query', - 'name': 'max_page_size', - 'required': true, - 'type': 'integer', - }, - { - 'in': 'query', - 'name': 'page_token', - 'required': true, - 'type': 'string', - }, - ], }, 'post': { + 'description': 'Create method for isbn', + 'operationId': 'CreateIsbn', 'responses': { '200': @@ -71,12 +78,12 @@ }, 'requestBody': { - 'required': true, 'content': { 'application/json': { 'schema': { '$ref': '#/components/schemas/isbn' } }, }, + 'required': true, }, }, }, @@ -84,6 +91,17 @@ { 'get': { + 'description': 'Get method for isbn', + 'operationId': 'GetIsbn', + 'parameters': + [ + { + 'name': 'isbn', + 'in': 'path', + 'required': true, + 'schema': { 'type': 'string' }, + }, + ], 'responses': { '200': @@ -99,21 +117,27 @@ }, }, }, - 'parameters': - [ - { - 'in': 'path', - 'name': 'isbn', - 'required': true, - 'type': 'string', - }, - ], }, }, '/publishers': { 'get': { + 'description': 'List method for publisher', + 'operationId': 'ListPublisher', + 'parameters': + [ + { + 'name': 'max_page_size', + 'in': 'query', + 'schema': { 'type': 'integer' }, + }, + { + 'name': 'page_token', + 'in': 'query', + 'schema': { 'type': 'string' }, + }, + ], 'responses': { '200': @@ -142,24 +166,11 @@ }, }, }, - 'parameters': - [ - { - 'in': 'query', - 'name': 'max_page_size', - 'required': true, - 'type': 'integer', - }, - { - 'in': 'query', - 'name': 'page_token', - 'required': true, - 'type': 'string', - }, - ], }, 'post': { + 'description': 'Create method for publisher', + 'operationId': 'CreatePublisher', 'responses': { '200': @@ -175,18 +186,8 @@ }, }, }, - 'parameters': - [ - { - 'in': 'query', - 'name': 'id', - 'required': true, - 'type': 'string', - }, - ], 'requestBody': { - 'required': true, 'content': { 'application/json': @@ -195,27 +196,25 @@ { '$ref': '#/components/schemas/publisher' }, }, }, + 'required': true, }, }, }, '/publishers/{publisher}': { - 'delete': + 'get': { - 'responses': { '200': { 'description': '', 'content': null } }, + 'description': 'Get method for publisher', + 'operationId': 'GetPublisher', 'parameters': [ { - 'in': 'path', 'name': 'publisher', + 'in': 'path', 'required': true, - 'type': 'string', + 'schema': { 'type': 'string' }, }, - { 'in': 'query', 'name': 'force', 'type': 'boolean' }, ], - }, - 'get': - { 'responses': { '200': @@ -231,18 +230,20 @@ }, }, }, + }, + 'patch': + { + 'description': 'Update method for publisher', + 'operationId': 'UpdatePublisher', 'parameters': [ { - 'in': 'path', 'name': 'publisher', + 'in': 'path', 'required': true, - 'type': 'string', + 'schema': { 'type': 'string' }, }, ], - }, - 'patch': - { 'responses': { '200': @@ -250,7 +251,7 @@ 'description': 'Successful response', 'content': { - 'application/merge-patch+json': + 'application/json': { 'schema': { '$ref': '#/components/schemas/publisher' }, @@ -258,30 +259,32 @@ }, }, }, - 'parameters': - [ - { - 'in': 'path', - 'name': 'publisher', - 'required': true, - 'type': 'string', - }, - ], 'requestBody': { - 'required': true, 'content': { - 'application/merge-patch+json': + 'application/json': { 'schema': { '$ref': '#/components/schemas/publisher' }, }, }, + 'required': true, }, }, 'put': { + 'description': 'Apply method for publisher', + 'operationId': 'ApplyPublisher', + 'parameters': + [ + { + 'name': 'publisher', + 'in': 'path', + 'required': true, + 'schema': { 'type': 'string' }, + }, + ], 'responses': { '200': @@ -297,18 +300,8 @@ }, }, }, - 'parameters': - [ - { - 'in': 'path', - 'name': 'publisher', - 'required': true, - 'type': 'string', - }, - ], 'requestBody': { - 'required': true, 'content': { 'application/json': @@ -317,6 +310,34 @@ { '$ref': '#/components/schemas/publisher' }, }, }, + 'required': true, + }, + }, + 'delete': + { + 'description': 'Delete method for publisher', + 'operationId': 'DeletePublisher', + 'parameters': + [ + { + 'name': 'publisher', + 'in': 'path', + 'required': true, + 'schema': { 'type': 'string' }, + }, + { + 'name': 'force', + 'in': 'query', + 'schema': { 'type': 'boolean' }, + }, + ], + 'responses': + { + '204': + { + 'description': 'Successful response', + 'content': { 'application/json': { 'schema': {} } }, + }, }, }, }, @@ -324,6 +345,27 @@ { 'get': { + 'description': 'List method for book', + 'operationId': 'ListBook', + 'parameters': + [ + { + 'name': 'publisher', + 'in': 'path', + 'required': true, + 'schema': { 'type': 'string' }, + }, + { + 'name': 'max_page_size', + 'in': 'query', + 'schema': { 'type': 'integer' }, + }, + { + 'name': 'page_token', + 'in': 'query', + 'schema': { 'type': 'string' }, + }, + ], 'responses': { '200': @@ -346,36 +388,31 @@ '$ref': '#/components/schemas/book', }, }, + 'unreachable': + { + 'type': 'array', + 'items': { 'type': 'string' }, + }, }, }, }, }, }, }, + }, + 'post': + { + 'description': 'Create method for book', + 'operationId': 'CreateBook', 'parameters': [ { - 'in': 'path', 'name': 'publisher', + 'in': 'path', 'required': true, - 'type': 'string', - }, - { - 'in': 'query', - 'name': 'max_page_size', - 'required': true, - 'type': 'integer', - }, - { - 'in': 'query', - 'name': 'page_token', - 'required': true, - 'type': 'string', + 'schema': { 'type': 'string' }, }, ], - }, - 'post': - { 'responses': { '200': @@ -391,56 +428,38 @@ }, }, }, - 'parameters': - [ - { - 'in': 'path', - 'name': 'publisher', - 'required': true, - 'type': 'string', - }, - { - 'in': 'query', - 'name': 'id', - 'required': true, - 'type': 'string', - }, - ], 'requestBody': { - 'required': true, 'content': { 'application/json': { 'schema': { '$ref': '#/components/schemas/book' } }, }, + 'required': true, }, }, }, '/publishers/{publisher}/books/{book}': { - 'delete': + 'get': { - 'responses': { '200': { 'description': '', 'content': null } }, + 'description': 'Get method for book', + 'operationId': 'GetBook', 'parameters': [ { - 'in': 'path', 'name': 'publisher', + 'in': 'path', 'required': true, - 'type': 'string', + 'schema': { 'type': 'string' }, }, { - 'in': 'path', 'name': 'book', + 'in': 'path', 'required': true, - 'type': 'string', + 'schema': { 'type': 'string' }, }, - { 'in': 'query', 'name': 'force', 'type': 'boolean' }, ], - }, - 'get': - { 'responses': { '200': @@ -456,24 +475,26 @@ }, }, }, + }, + 'patch': + { + 'description': 'Update method for book', + 'operationId': 'UpdateBook', 'parameters': [ { - 'in': 'path', 'name': 'publisher', + 'in': 'path', 'required': true, - 'type': 'string', + 'schema': { 'type': 'string' }, }, { - 'in': 'path', 'name': 'book', + 'in': 'path', 'required': true, - 'type': 'string', + 'schema': { 'type': 'string' }, }, ], - }, - 'patch': - { 'responses': { '200': @@ -481,7 +502,7 @@ 'description': 'Successful response', 'content': { - 'application/merge-patch+json': + 'application/json': { 'schema': { '$ref': '#/components/schemas/book' }, @@ -489,33 +510,35 @@ }, }, }, + 'requestBody': + { + 'content': + { + 'application/json': + { 'schema': { '$ref': '#/components/schemas/book' } }, + }, + 'required': true, + }, + }, + 'put': + { + 'description': 'Apply method for book', + 'operationId': 'ApplyBook', 'parameters': [ { - 'in': 'path', 'name': 'publisher', + 'in': 'path', 'required': true, - 'type': 'string', + 'schema': { 'type': 'string' }, }, { - 'in': 'path', 'name': 'book', + 'in': 'path', 'required': true, - 'type': 'string', + 'schema': { 'type': 'string' }, }, ], - 'requestBody': - { - 'required': true, - 'content': - { - 'application/merge-patch+json': - { 'schema': { '$ref': '#/components/schemas/book' } }, - }, - }, - }, - 'put': - { 'responses': { '200': @@ -531,28 +554,46 @@ }, }, }, + 'requestBody': + { + 'content': + { + 'application/json': + { 'schema': { '$ref': '#/components/schemas/book' } }, + }, + 'required': true, + }, + }, + 'delete': + { + 'description': 'Delete method for book', + 'operationId': 'DeleteBook', 'parameters': [ { - 'in': 'path', 'name': 'publisher', + 'in': 'path', 'required': true, - 'type': 'string', + 'schema': { 'type': 'string' }, }, { - 'in': 'path', 'name': 'book', + 'in': 'path', 'required': true, - 'type': 'string', + 'schema': { 'type': 'string' }, + }, + { + 'name': 'force', + 'in': 'query', + 'schema': { 'type': 'boolean' }, }, ], - 'requestBody': + 'responses': { - 'required': true, - 'content': + '204': { - 'application/json': - { 'schema': { '$ref': '#/components/schemas/book' } }, + 'description': 'Successful response', + 'content': { 'application/json': { 'schema': {} } }, }, }, }, @@ -561,6 +602,33 @@ { 'get': { + 'description': 'List method for book-edition', + 'operationId': 'ListBookEdition', + 'parameters': + [ + { + 'name': 'publisher', + 'in': 'path', + 'required': true, + 'schema': { 'type': 'string' }, + }, + { + 'name': 'book', + 'in': 'path', + 'required': true, + 'schema': { 'type': 'string' }, + }, + { + 'name': 'max_page_size', + 'in': 'query', + 'schema': { 'type': 'integer' }, + }, + { + 'name': 'page_token', + 'in': 'query', + 'schema': { 'type': 'string' }, + }, + ], 'responses': { '200': @@ -589,36 +657,26 @@ }, }, }, + }, + 'post': + { + 'description': 'Create method for book-edition', + 'operationId': 'CreateBookEdition', 'parameters': [ { - 'in': 'path', 'name': 'publisher', - 'required': true, - 'type': 'string', - }, - { 'in': 'path', - 'name': 'book', 'required': true, - 'type': 'string', + 'schema': { 'type': 'string' }, }, { - 'in': 'query', - 'name': 'max_page_size', - 'required': true, - 'type': 'integer', - }, - { - 'in': 'query', - 'name': 'page_token', + 'name': 'book', + 'in': 'path', 'required': true, - 'type': 'string', + 'schema': { 'type': 'string' }, }, ], - }, - 'post': - { 'responses': { '200': @@ -636,30 +694,8 @@ }, }, }, - 'parameters': - [ - { - 'in': 'path', - 'name': 'publisher', - 'required': true, - 'type': 'string', - }, - { - 'in': 'path', - 'name': 'book', - 'required': true, - 'type': 'string', - }, - { - 'in': 'query', - 'name': 'id', - 'required': true, - 'type': 'string', - }, - ], 'requestBody': { - 'required': true, 'content': { 'application/json': @@ -668,38 +704,37 @@ { '$ref': '#/components/schemas/book-edition' }, }, }, + 'required': true, }, }, }, '/publishers/{publisher}/books/{book}/editions/{book-edition}': { - 'delete': + 'get': { - 'responses': { '200': { 'description': '', 'content': null } }, + 'description': 'Get method for book-edition', + 'operationId': 'GetBookEdition', 'parameters': [ { - 'in': 'path', 'name': 'publisher', + 'in': 'path', 'required': true, - 'type': 'string', + 'schema': { 'type': 'string' }, }, { - 'in': 'path', 'name': 'book', + 'in': 'path', 'required': true, - 'type': 'string', + 'schema': { 'type': 'string' }, }, { - 'in': 'path', 'name': 'book-edition', + 'in': 'path', 'required': true, - 'type': 'string', + 'schema': { 'type': 'string' }, }, ], - }, - 'get': - { 'responses': { '200': @@ -717,33 +752,63 @@ }, }, }, + }, + 'delete': + { + 'description': 'Delete method for book-edition', + 'operationId': 'DeleteBookEdition', 'parameters': [ { - 'in': 'path', 'name': 'publisher', + 'in': 'path', 'required': true, - 'type': 'string', + 'schema': { 'type': 'string' }, }, { - 'in': 'path', 'name': 'book', + 'in': 'path', 'required': true, - 'type': 'string', + 'schema': { 'type': 'string' }, }, { - 'in': 'path', 'name': 'book-edition', + 'in': 'path', 'required': true, - 'type': 'string', + 'schema': { 'type': 'string' }, }, ], + 'responses': + { + '204': + { + 'description': 'Successful response', + 'content': { 'application/json': { 'schema': {} } }, + }, + }, }, }, - '/publishers/{publisher}:archive': + '/publishers/{publisher}/books/{book}:archive': { 'post': { + 'description': 'Custom method archive for book', + 'operationId': ':ArchiveBook', + 'parameters': + [ + { + 'name': 'publisher', + 'in': 'path', + 'required': true, + 'schema': { 'type': 'string' }, + }, + { + 'name': 'book', + 'in': 'path', + 'required': true, + 'schema': { 'type': 'string' }, + }, + ], 'responses': { '200': @@ -754,24 +819,15 @@ 'application/json': { 'schema': - { '$ref': '#/components/schemas/publisher' }, + { '$ref': '#/components/schemas/book' }, }, }, }, }, - 'parameters': - [ - { - 'in': 'path', - 'name': 'publisher', - 'required': true, - 'type': 'string', - }, - ], 'requestBody': { - 'required': true, 'content': { 'application/json': { 'schema': {} } }, + 'required': true, }, }, }, @@ -783,10 +839,23 @@ 'book': { 'type': 'object', - 'required': ['isbn', 'price', 'published'], 'properties': { - 'author': { 'type': 'array', 'items': { 'type': 'object' } }, + 'author': + { + 'type': 'array', + 'items': + { + 'type': 'object', + 'properties': + { + 'firstName': { 'type': 'string' }, + 'lastName': { 'type': 'string' }, + }, + 'x-aep-field-numbers': + { '1': 'firstName', '2': 'lastName' }, + }, + }, 'edition': { 'type': 'integer', 'format': 'int32' }, 'isbn': { 'type': 'array', 'items': { 'type': 'string' } }, 'path': { 'type': 'string', 'readOnly': true }, @@ -797,14 +866,23 @@ { 'singular': 'book', 'plural': 'books', - 'patterns': ['/publishers/{publisher}/books/{book}'], + 'patterns': ['publishers/{publisher}/books/{book}'], 'parents': ['publisher'], }, + 'x-aep-field-numbers': + { + '0': 'author', + '1': 'isbn', + '10018': 'path', + '2': 'price', + '3': 'published', + '4': 'edition', + }, + 'required': ['isbn', 'price', 'published'], }, 'book-edition': { 'type': 'object', - 'required': ['displayname'], 'properties': { 'displayname': { 'type': 'string' }, @@ -816,10 +894,12 @@ 'plural': 'book-editions', 'patterns': [ - '/publishers/{publisher}/books/{book}/editions/{book-edition}', + 'publishers/{publisher}/books/{book}/editions/{book-edition}', ], 'parents': ['book'], }, + 'x-aep-field-numbers': { '1': 'displayname', '10018': 'path' }, + 'required': ['displayname'], }, 'isbn': { @@ -829,8 +909,9 @@ { 'singular': 'isbn', 'plural': 'isbns', - 'patterns': ['/isbns/{isbn}'], + 'patterns': ['isbns/{isbn}'], }, + 'x-aep-field-numbers': { '10018': 'path' }, }, 'publisher': { @@ -844,8 +925,9 @@ { 'singular': 'publisher', 'plural': 'publishers', - 'patterns': ['/publishers/{publisher}'], + 'patterns': ['publishers/{publisher}'], }, + 'x-aep-field-numbers': { '1': 'description', '10018': 'path' }, }, }, },