├── .gitignore ├── README.md ├── bookstore ├── 3a-design-rest │ ├── representation-examples │ │ ├── book-serialization.json │ │ ├── book-hal.json │ │ ├── book-apijson.json │ │ └── book-uber.json │ ├── design-sequence-diagram-1.mmd │ ├── ShoppingAPI.design.md │ ├── Shopping-API-REST.oas3.yaml │ └── Order-Creation-API-REST.oas3.yaml ├── 1-align │ ├── 2-activities.md │ ├── 1-job-stories.md │ └── 3-activity-steps.md ├── 2-define │ ├── modeling-sequence-diagram-1.mmd │ ├── resources.md │ └── ShoppingAPI.profile.md ├── 3c-design-grpc │ └── Shopping-API.proto3 ├── 3d-design-async │ └── Shopping-API-events-v1.asyncapi.yaml └── 3b-design-graphql │ └── Shopping-API.graphql └── description-format-examples ├── Airport-example.graphql ├── Docs-Example.schema.json ├── Airport-example.odata ├── Docs-Example.alps.xml ├── Docs-Example.apis.json.yaml ├── Docs-Example_v1.0.graphql ├── Docs-Example_v1.0.apib.md ├── Docs-Example_v1.0.oas3.yaml └── Docs-Example_v1.0.raml10.yaml /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Align-Define-Design-Refine (ADDR) Process Examples 2 | 3 | Examples of the ADDR API process for use in our [LaunchAny workshops](https://launchany.com/api-training) or for self-paced learning. 4 | -------------------------------------------------------------------------------- /bookstore/3a-design-rest/representation-examples/book-serialization.json: -------------------------------------------------------------------------------- 1 | { 2 | "bookId": "12345", 3 | "isbn": "978-0321834577", 4 | "title": "Implementing Domain-Driven Design", 5 | "description": "With Implementing Domain-Driven Design, Vaughn has made an important contribution not only to the literature of the Domain-Driven Design community, but also to the literature of the broader enterprise application architecture field.", 6 | "authors": [ 7 | { "authorId": "765", "fullName": "Vaughn Vernon" } 8 | ] 9 | } 10 | -------------------------------------------------------------------------------- /bookstore/1-align/2-activities.md: -------------------------------------------------------------------------------- 1 | | Digital Capability | Activity | Participants | Description | 2 | |--------------------|------------------|-----------------------|---------------------------------------------------------------------| 3 | | Place an Order | Browse for Books | Customer | Browse or search for books | 4 | | Place an Order | Shop for Books | Customer, Call Center | A customer adds books to a cart | 5 | | Place an Order | Create an Order | Customer, Call Center | A customer places the order using the contents of the shopping cart | 6 | -------------------------------------------------------------------------------- /description-format-examples/Airport-example.graphql: -------------------------------------------------------------------------------- 1 | POST /graphql 2 | 3 | { 4 | airports(iataCode : "SFO") 5 | } 6 | 7 | { 8 | "data" : { 9 | { 10 | "Name": "San Francisco International Airport", 11 | "iataCode": "SFO", 12 | "Location": { 13 | "Address": "South McDonnell Road, San Francisco, CA 94128", 14 | "City": { 15 | "CountryRegion": "United States", 16 | "Name": "San Francisco", 17 | "Region": "California" 18 | }, 19 | "Loc": { 20 | "type": "Point", 21 | "coordinates": [ 22 | -122.374722222222, 23 | 37.6188888888889 24 | ] 25 | } 26 | } 27 | } 28 | } 29 | } -------------------------------------------------------------------------------- /bookstore/3a-design-rest/design-sequence-diagram-1.mmd: -------------------------------------------------------------------------------- 1 | sequenceDiagram 2 | participant Customer 3 | participant Shopping API 4 | 5 | Customer->>Shopping API: GET /books 6 | Shopping API-->>Customer: Books[] 7 | Customer->>Shopping API: POST /carts { bookId: 12345, qty: 1 } 8 | Shopping API-->>Customer: Cart { cartId: 456 } 9 | Customer->>Shopping API: DELETE /carts/456/items/1 10 | 11 | Customer->>Shopping API: POST /books/search { q: "API" } 12 | Shopping API-->>Customer: Books[] 13 | Customer->>Shopping API: POST /carts/456/items { bookId: 12345, qty: 1 } 14 | Shopping API-->>Customer: Cart { cartId: 456, ... } 15 | 16 | Customer->>Shopping API: GET /carts/456 17 | Shopping API-->>Customer: Cart { cartId: 456, ... } 18 | -------------------------------------------------------------------------------- /bookstore/3a-design-rest/representation-examples/book-hal.json: -------------------------------------------------------------------------------- 1 | { 2 | "bookId": "12345", 3 | "isbn": "978-0321834577", 4 | "title": "Implementing Domain-Driven Design", 5 | "description": "With Implementing Domain-Driven Design, Vaughn has made an important contribution not only to the literature of the Domain-Driven Design community, but also to the literature of the broader enterprise application architecture field.", 6 | "_links": { 7 | "self": { "href": "/books/12345" } 8 | }, 9 | "_embedded": { 10 | "authors": [ 11 | { 12 | "authorId": "765", 13 | "fullName": "Vaughn Vernon", 14 | "_links": { 15 | "self": { "href": "/authors/765" }, 16 | "authoredBooks": { "href": "/books?authorId=765" } 17 | } 18 | } 19 | ] 20 | } 21 | } 22 | -------------------------------------------------------------------------------- /description-format-examples/Docs-Example.schema.json: -------------------------------------------------------------------------------- 1 | { 2 | "$id": "https://example.com/BookSummary.schema.json", 3 | "$schema": "http://json-schema.org/draft-07/schema#", 4 | "description": "Summarizes a book that is stocked by the book store...", 5 | "type": "object", 6 | "properties": { 7 | "bookId": { 8 | "type": "string" 9 | }, 10 | "isbn": { 11 | "type": "string" 12 | }, 13 | "title": { 14 | "type": "string" 15 | }, 16 | "authors": { 17 | "type": "array", 18 | "items": { 19 | "$ref": "#/definitions/BookAuthor" 20 | } 21 | } 22 | }, 23 | "definitions": { 24 | "BookAuthor": { 25 | "type": "object", 26 | "properties": { 27 | "authorId": { 28 | "type": "string" 29 | }, 30 | "fullName": { 31 | "type": "string" 32 | } 33 | } 34 | } 35 | } 36 | } 37 | -------------------------------------------------------------------------------- /bookstore/3a-design-rest/representation-examples/book-apijson.json: -------------------------------------------------------------------------------- 1 | { 2 | "data": { 3 | "type": "books", 4 | "id": "12345", 5 | "attributes": { 6 | "isbn": "978-0321834577", 7 | "title": "Implementing Domain-Driven Design", 8 | "description": "With Implementing Domain-Driven Design, Vaughn has made an important contribution not only to the literature of the Domain-Driven Design community, but also to the literature of the broader enterprise application architecture field." 9 | }, 10 | "relationships": { 11 | "authors": { 12 | "data": [ 13 | {"id": "765", "type": "authors"} 14 | ] 15 | } 16 | }, 17 | "included": [ 18 | { 19 | "type": "authors", 20 | "id": "765", 21 | "fullName": "Vaughn Vernon", 22 | "links": { 23 | "self": { "href": "/authors/765" }, 24 | "authoredBooks": { "href": "/books?authorId=765" } 25 | } 26 | } 27 | } 28 | } 29 | -------------------------------------------------------------------------------- /bookstore/2-define/modeling-sequence-diagram-1.mmd: -------------------------------------------------------------------------------- 1 | sequenceDiagram 2 | participant Customer 3 | participant Shopping API 4 | participant Order Creation API 5 | participant Payment Processing API 6 | 7 | Customer->>Shopping API: listBooks() 8 | Shopping API-->>Customer: Books[] 9 | Customer->>Shopping API: addBookToCart(bookId) 10 | Shopping API-->>Customer: Cart 11 | Customer->>Shopping API: removeBookFromCart(bookId) 12 | 13 | Customer->>Shopping API: searchBooks(searchQuery) 14 | Shopping API-->>Customer: Books[] 15 | Customer->>Shopping API: addBookToCart(bookId) 16 | Shopping API-->>Customer: Cart 17 | 18 | Customer->>Shopping API: viewCart() 19 | Shopping API-->>Customer: Cart 20 | Customer->>Order Creation API: createOrderFromCart(cartId) 21 | Order Creation API-->>Customer: Order 22 | 23 | Customer->>Payment Processing API: payForOrder(orderId) 24 | Payment Processing API-->>Customer: PaymentDetails 25 | -------------------------------------------------------------------------------- /description-format-examples/Airport-example.odata: -------------------------------------------------------------------------------- 1 | GET /OData/Airports?$filter=contains(Location/Address, 'San Francisco') 2 | 3 | { 4 | "@odata.context": "/OData/$metadata#Airports", 5 | "value": [ 6 | { 7 | "@odata.id": "/OData/Airports('KSFO')", 8 | "@odata.editLink": "/OData/Airports('KSFO')", 9 | "IcaoCode": "KSFO", 10 | "Name": "San Francisco International Airport", 11 | "IataCode": "SFO", 12 | "Location": { 13 | "Address": "South McDonnell Road, San Francisco, CA 94128", 14 | "City": { 15 | "CountryRegion": "United States", 16 | "Name": "San Francisco", 17 | "Region": "California" 18 | }, 19 | "Loc": { 20 | "type": "Point", 21 | "coordinates": [ 22 | -122.374722222222, 23 | 37.6188888888889 24 | ], 25 | "crs": { 26 | "type": "name", 27 | "properties": { 28 | "name": "EPSG:4326" 29 | } 30 | } 31 | } 32 | } 33 | } 34 | ] 35 | } 36 | -------------------------------------------------------------------------------- /bookstore/1-align/1-job-stories.md: -------------------------------------------------------------------------------- 1 | | Job Story ID | When... (Triggering Situation) | I want to... (Digital Capability) | So I can... (Outcome) | 2 | |--------------|---------------------------------------------------------------------------|---------------------------------------|-------------------------------------------------------------| 3 | | 1 | I want to see the new books that have been released | List recently added books | Keep up with the latest watercooler talk | 4 | | 2 | I want to find a book that will be entertaining or teach me something new | Search for a book by topic or keyword | Browse related books | 5 | | 3 | I encounter an unfamiliar book | View a book’s details and reviews | Determine if the book is of interest to me | 6 | | 4 | I find one or more books that I wish to buy | Place an order | Buy the books and have them shipped to my preferred address | 7 | | 5 | I am uncertain of when my order will arrive | View the status of an order | Confirm the date that the order will arrive | 8 | -------------------------------------------------------------------------------- /bookstore/1-align/3-activity-steps.md: -------------------------------------------------------------------------------- 1 | | Digital Capability | Activity | Activity Step | Participants | Description | 2 | |--------------------|------------------|------------------------|-----------------------|-----------------------------------------------| 3 | | Place an Order | Browse for Books | List Books | Customer, Call Center | List books by category or release date | 4 | | Place an Order | Browse for Books | Search for Books | Customer, Call Center | Search for books by author, title | 5 | | Place an Order | Shop for Books | Add Books to Cart | Customer, Call Center | Add a book to the customer's cart | 6 | | Place an Order | Shop for Books | Remove Books from Cart | Customer, Call Center | Remove a book from the customer's cart | 7 | | Place an Order | Shop for Books | Clear Cart | Customer, Call Center | Remove all books from the customer's cart | 8 | | Place an Order | Shop for Books | View Cart | Customer, Call Center | View the current cart and total | 9 | | Place an Order | Create an Order | Checkout | Customer, Call Center | Create an order from the contents of the cart | 10 | | Place an Order | Create an Order | Pay for Order | Customer, Call Center | Accept and process payment for the order | 11 | -------------------------------------------------------------------------------- /bookstore/3c-design-grpc/Shopping-API.proto3: -------------------------------------------------------------------------------- 1 | service ShoppingCart { 2 | rpc ListBooks(ListBooksRequest) returns (ListBooksResponse) {} 3 | 4 | rpc SearchBooks(SearchBooksRequest) returns (SearchBooksResponse) {} 5 | 6 | rpc ViewCart(ViewCartRequest) returns (Cart) {} 7 | 8 | rpc ClearCart(ClearCartRequest) returns (Cart) {} 9 | 10 | rpc AddItemToCart(AddCartItemRequest) returns (Cart) {} 11 | 12 | rpc RemoveItemFromCart(RemoveCartItemRequest) returns (Cart) {} 13 | 14 | rpc GetAuthorDetails() returns (Author) {} 15 | 16 | } 17 | 18 | message ListBooksRequest { 19 | string category_id = 1; 20 | string release_date = 2; 21 | } 22 | 23 | message SearchBooksRequest { 24 | string query = 1; 25 | } 26 | 27 | message SearchBooksResponse { 28 | int32 page_number = 1; 29 | int32 result_per_page = 2 [default = 10]; 30 | repeated Book books = 3; 31 | } 32 | 33 | message ViewCartRequest { 34 | string cart_id = 1; 35 | } 36 | 37 | message ClearCartRequest { 38 | string cart_id = 1; 39 | } 40 | 41 | message AddCartItemRequest { 42 | string cart_id = 1; 43 | string book_id = 2; 44 | int32 quantity = 3; 45 | } 46 | 47 | message RemoveCartItemRequest { 48 | string cart_id = 1; 49 | string cart_item_id = 2; 50 | } 51 | 52 | message CartItem { 53 | string cart_item_id = 1; 54 | Book book = 2; 55 | int32 quantity = 3; 56 | } 57 | 58 | message Cart { 59 | string cart_id = 1; 60 | repeated CartItem cart_items = 2; 61 | } 62 | 63 | -------------------------------------------------------------------------------- /bookstore/3d-design-async/Shopping-API-events-v1.asyncapi.yaml: -------------------------------------------------------------------------------- 1 | asyncapi: 2.0.0 2 | info: 3 | title: Shopping API Events 4 | version: 1.0.0 5 | description: | 6 | An example of some of the events published during the bookstore's shopping cart experience... 7 | channels: 8 | books.searched: 9 | subscribe: 10 | message: 11 | $ref: '#/components/messages/BooksSearched' 12 | carts.itemAdded: 13 | subscribe: 14 | message: 15 | $ref: '#/components/messages/CartItemAdded' 16 | components: 17 | messages: 18 | BooksSearched: 19 | payload: 20 | type: object 21 | properties: 22 | queryStringFilter: 23 | type: string 24 | description: The query string used in the search filter 25 | categoryIdFilter: 26 | type: string 27 | description: The category ID used in the search filter 28 | releaseDateFilter: 29 | type: string 30 | description: The release date used in the search filter 31 | CartItemAdded: 32 | payload: 33 | type: object 34 | properties: 35 | cartId: 36 | type: string 37 | description: The cartId where the book was added 38 | bookId: 39 | type: string 40 | description: The book ID that was added to the cart 41 | quantity: 42 | type: integer 43 | description: The quantity of books added 44 | -------------------------------------------------------------------------------- /bookstore/3b-design-graphql/Shopping-API.graphql: -------------------------------------------------------------------------------- 1 | # API Name: "Bookstore Shopping API Example" 2 | # 3 | # The Bookstore Example REST-based API supports the shopping experience of an online bookstore. The API includes the following capabilities and operations... 4 | # 5 | 6 | type Query { 7 | listBooks(input: ListBooksInput!): BooksResponse! 8 | searchBooks(input: SearchBooksInput!): BooksResponse! 9 | getCart(input: GetCartInput!): Cart! 10 | getAuthorDetails(input: GetAuthorDetailsInput!): BookAuthor! 11 | } 12 | 13 | type Mutation { 14 | clearCart(): Cart 15 | addItemToCart(input: AddCartItemInput!): Cart 16 | removeItemFromCart(input: RemoveCartItemInput!): Cart 17 | } 18 | 19 | type BooksResponse { 20 | books: [BookSummary!] 21 | } 22 | 23 | type BookSummary { 24 | bookId: String! 25 | isbn: String! 26 | title: String! 27 | authors: [BookAuthor!] 28 | } 29 | 30 | type BookAuthor { 31 | authorId: String! 32 | fullName: String! 33 | } 34 | 35 | type Cart { 36 | cartId: String! 37 | cartItems: [CartItem!] 38 | } 39 | 40 | type CartItem { 41 | cartItemId: String! 42 | bookId: String! 43 | quantity: Int! 44 | } 45 | 46 | input ListBooksInput { 47 | offset: Int! 48 | limit: Int! 49 | } 50 | 51 | input SearchBooksInput { 52 | q: String! 53 | offset: Int! 54 | limit: Int! 55 | } 56 | 57 | input GetAuthorDetailsInput { 58 | authorId: String! 59 | } 60 | 61 | input AddCartItemInput { 62 | cartId: String! 63 | bookId: String! 64 | quantity: Int! 65 | } 66 | 67 | input RemoveCartItemInput { 68 | cartId: String! 69 | cartItemId: String! 70 | } 71 | 72 | -------------------------------------------------------------------------------- /description-format-examples/Docs-Example.alps.xml: -------------------------------------------------------------------------------- 1 | 2 | A contact list. 3 | 4 | 5 | 6 | 7 | 8 | Provides a paginated list of books based on the search criteria provided. 9 | 10 | 11 | A query string to use for filtering books by title and description. 12 | 13 | 14 | 15 | 16 | 17 | 18 | An internal identifier, separate from the ISBN, that identifies the book within the inventory 19 | 20 | 21 | The ISBN of the book 22 | 23 | 24 | The book title, e.g. A Practical Approach to API Design 25 | 26 | 27 | Summarizes a book that is stocked by the book store 28 | 29 | An internal identifier that references the author 30 | 31 | 32 | The full name of the author, e.g. D. Keith Casey 33 | 34 | 35 | 36 | 37 | -------------------------------------------------------------------------------- /description-format-examples/Docs-Example.apis.json.yaml: -------------------------------------------------------------------------------- 1 | name: Bookstore Example 2 | type: Index 3 | description: The Bookstore API supports the shopping experience of an online bookstore, along with ... 4 | tags: 5 | - Application Programming Interface 6 | - API 7 | created: '2020-12-10' 8 | modified: '2020-12-10' 9 | url: http://example.com/apis.json 10 | specificationVersion: '0.14' 11 | apis: 12 | - name: Bookstore Shopping API 13 | description: The Bookstore Example REST-based API supports the shopping experience of an online bookstore 14 | humanURL: http://example.com 15 | baseURL: http://api.example.com 16 | tags: 17 | - API 18 | - Application Programming Interface 19 | 20 | properties: 21 | - type: Documentation 22 | url: https://example.com/documentation 23 | - type: OpenAPI 24 | url: http://example.com/openapi.json 25 | - type: JSONSchema 26 | url: http://example.com/json-schema.json 27 | 28 | contact: 29 | - FN: APIs.json 30 | email: info@apisjson.org 31 | X-twitter: apisjson 32 | 33 | specifications: 34 | - name: OpenAPI 35 | description: OpenAPI is used as the contract for all of our APIs. 36 | url: https://openapis.org 37 | - name: JSON Schema 38 | description: JSON Schema is used to define all of the underlying objects used. 39 | url: https://json-schema.org/ 40 | 41 | common: 42 | - type: Signup 43 | url: https://example.com/signup 44 | - type: Authentication 45 | url: http://example.com/authentication 46 | - type: Login 47 | url: https://example.com/login 48 | - type: Blog 49 | url: http://example.com/blog 50 | - type: Pricing 51 | url: http://example.com/pricing 52 | -------------------------------------------------------------------------------- /bookstore/2-define/resources.md: -------------------------------------------------------------------------------- 1 | # Modeled Resources 2 | 3 | ## Book 4 | 5 | | Property Name | Description | 6 | |---------------|-------------------------------| 7 | | title | The book title | 8 | | isbn | The unique ISBN of the book | 9 | | authors | List of Book Author resources | 10 | 11 | ## Book Author 12 | 13 | | Property Name | Description | 14 | |---------------|-----------------------------| 15 | | fullName | The full name of the author | 16 | 17 | ## Cart 18 | 19 | | Property Name | Description | 20 | |---------------|----------------------------------------------| 21 | | cartItems | The items currently in the cart for purchase | 22 | | subtotal | The total cost of all books in the cart | 23 | | salesTax | The sales tax to be applied | 24 | | vatTax | Any VAT tax to be applied | 25 | | cartTotal | The total cost of the cart | 26 | 27 | 28 | ## Cart Item 29 | 30 | | Property Name | Description | 31 | |---------------|-----------------------------------------------------------------------------------| 32 | | book | The books currently in the cart for purchase | 33 | | qty | The quantity of the item in the cart (default 1) | 34 | | unitPrice | The unit price represented as a whole number. For example, $1.99 USD would be 199 | 35 | | | | 36 | 37 | -------------------------------------------------------------------------------- /bookstore/3a-design-rest/ShoppingAPI.design.md: -------------------------------------------------------------------------------- 1 | | Resource Path | Operation Name | HTTP Method | Description | Request Details | Response Details | Response Code(s) | 2 | |------------------------------------|----------------------|-------------|-------------------------------------------|--------------------------|------------------|------------------| 3 | | /books | listBooks() | GET | List books by category or release date | categoryId releaseDate | Books[] | 200 | 4 | | /books/search | searchBooks() | POST | Search for books by author, title | searchQuery | Books[] | 200 | 5 | | /carts/{cartId} | viewCart() | GET | View the current cart and total | cartId | Cart | 200, 404 | 6 | | /carts/{cartId} | clearCart() | DELETE | Remove all books from the customer's cart | cartId | Cart | 204, 404 | 7 | | /carts/{cartId}/items | addItemToCart() | POST | Add a book to the customer's cart | cartId | Cart | 201, 400 | 8 | | /carts/{cartId}/items/{cartItemId} | removeItemFromCart() | DELETE | Remove a book from the customer's cart | cartId cartItemId | Cart | 204, 404 | 9 | | /authors | getAuthorDetails() | GET | Retrieve the details of an author | authorId | BookAuthor | 200, 404 | 10 | -------------------------------------------------------------------------------- /description-format-examples/Docs-Example_v1.0.graphql: -------------------------------------------------------------------------------- 1 | # API Name: "Bookstore Shopping API Example" 2 | # 3 | # The Bookstore Example REST-based API supports the shopping experience of an online bookstore. The API includes the following capabilities and operations... 4 | # 5 | 6 | "A list of book summaries as a result of a list or filter request..." 7 | type ListBooksResponse { 8 | books: [BookSummary!] 9 | } 10 | 11 | "Summarizes a book that is stocked by the book store..." 12 | type BookSummary { 13 | "An internal identifier, separate from the ISBN, that identifies the book within the inventory" 14 | bookId: String! 15 | "The ISBN of the book" 16 | isbn: String! 17 | "The book title, e.g. A Practical Approach to API Design" 18 | title: String! 19 | authors: [BookAuthor!] 20 | } 21 | 22 | "Represents a single author for a book. Since a book may have more than one author, ..." 23 | type BookAuthor { 24 | "An internal identifier that references the author" 25 | authorId: String! 26 | "The full name of the author, e.g. D. Keith Casey" 27 | fullName: String! 28 | } 29 | 30 | input ListBooksInput { 31 | "A query string to use for filtering books by title and description. If not provided, all available books will be listed..." 32 | q: String! 33 | "A offset from which the list of books are retrieved, where an offset of 0 means the first page of results..." 34 | offset: Int! 35 | "Number of records to be included in API call, defaulting to 25 records at a time if not provided..." 36 | limit: Int! 37 | "An OAuth 2.0 access token that authorizes your app to call this operation..." 38 | authorization: String! 39 | } 40 | 41 | type Query { 42 | "Provides a paginated list of books based on the search criteria provided..." 43 | listBooks(input: ListBooksInput!): ListBooksResponse! 44 | } 45 | 46 | schema { 47 | query: Query 48 | } 49 | -------------------------------------------------------------------------------- /bookstore/2-define/ShoppingAPI.profile.md: -------------------------------------------------------------------------------- 1 | # Shopping API 2 | 3 | * Supports the book browsing experience and cart management 4 | * Scope: Public 5 | 6 | | Operation Name | Description | Participants | Resource(s) | Emitted Events | Operation Details | Traits | 7 | |----------------------|-------------------------------------------|-----------------------|-------------------|------------------|----------------------------------------------------------------------------|----------------------------| 8 | | listBooks() | List books by category or release date | Customer, Call Center | Book, Book Author | Books.Listed | __Request Parameters:__ categoryId, releaseDate __Returns:__ Books[] | safe / synchronous | 9 | | searchBooks() | Search for books by author, title | Customer, Call Center | Book | Books.Searched | __Request Parameters:__ searchQuery __Returns:__ Books[] | safe / synchronous | 10 | | addItemToCart() | Add a book to the customer's cart | Customer, Call Center | Cart Item, Cart | Cart.ItemAdded | __Request Parameters:__ cartId, bookId, quantity __Returns:__ Cart | unsafe / synchronous | 11 | | removeItemFromCart() | Remove a book from the customer's cart | Customer, Call Center | Cart Item, Cart | Cart.ItemRemoved | __Request Parameters:__ cartItemId __Returns:__ Cart | idempotent / synchronous | 12 | | clearCart() | Remove all books from the customer's cart | Customer, Call Center | Cart | Cart.Cleared | __Request Parameters:__ cartId __Returns:__ Cart | safe / synchronous | 13 | | viewCart() | View the current cart and total | Customer, Call Center | Cart | Cart.Viewed | __Request Parameters:__ cartId __Returns:__ Cart | safe / synchronous | 14 | -------------------------------------------------------------------------------- /bookstore/3a-design-rest/representation-examples/book-uber.json: -------------------------------------------------------------------------------- 1 | { 2 | "uber" : 3 | { 4 | "version" : "1.0", 5 | "data" : 6 | [ 7 | 8 | {"rel" : ["self"], "url" : "http://example.org/"}, 9 | {"rel" : ["profile"], "url" : "http://example.org/profiles/books"}, 10 | { 11 | "name" : "searchBooks", 12 | "rel" : ["search","collection"], 13 | "url" : "http://example.org/books/search?q={query}", 14 | "templated" : "true" 15 | }, 16 | { 17 | "id" : "book-12345", 18 | "rel" : ["collection","http://example.org/rels/books"], 19 | "url" : "http://example.org/books/12345", 20 | "data" : 21 | [ 22 | { 23 | "name" : "bookId", 24 | "value" : "12345", 25 | "label" : "Book ID" 26 | }, 27 | { 28 | "name" : "isbn", 29 | "value" : "978-0321834577", 30 | "label" : "ISBN", 31 | "rel" : ["https://schema.org/isbn"] 32 | }, 33 | { 34 | "name" : "title", 35 | "value" : "Example Book", 36 | "label" : "Book Title", 37 | "rel" : ["https://schema.org/name"] 38 | }, 39 | { 40 | "name" : "description", 41 | "value" : "With Implementing Domain-Driven Design, Vaughn has made an important contribution not only to the literature of the Domain-Driven Design community, but also to the literature of the broader enterprise application architecture field.", 42 | "label" : "Book Description", 43 | "rel" : ["https://schema.org/description"] 44 | }, 45 | { 46 | "name" : "authors", 47 | "rel" : ["collection","http://example.org/rels/authors"], 48 | "data" : 49 | [ 50 | { 51 | "id" : "author-765", 52 | "rel" : ["http://schema.org/Person"], 53 | "url" : "http://example.org/authors/765", 54 | "data" : 55 | [ 56 | { 57 | "name" : "authorId", 58 | "value" : "765", 59 | "label" : "Author ID" 60 | }, 61 | { 62 | "name" : "fullName", 63 | "value" : "Vaughn Vernon", 64 | "label" : "Full Name", 65 | "rel" : "https://schema.org/name" 66 | } 67 | ] 68 | } 69 | ] 70 | }, 71 | ] 72 | } 73 | ] 74 | } 75 | } 76 | -------------------------------------------------------------------------------- /description-format-examples/Docs-Example_v1.0.apib.md: -------------------------------------------------------------------------------- 1 | FORMAT: 1A 2 | HOST: https://www.example.com 3 | 4 | # Bookstore Shopping API Example 5 | The Bookstore Example REST-based API supports the shopping experience of an online bookstore. The API includes the following capabilities and operations... 6 | 7 | # Group Books 8 | 9 | ## Books [/books{?q,offset,limit}] 10 | 11 | ### ListBooks [GET] 12 | Provides a paginated list of books based on the search criteria provided... 13 | + Parameters 14 | + q (string, optional) 15 | A query string to use for filtering books by title and description. If not provided, all available books will be listed... 16 | + offset (number, optional) - 17 | A offset from which the list of books are retrieved, where an offset of 0 means the first page of results... 18 | + Default: 0 19 | + limit (number, optional) - 20 | Number of records to be included in API call, defaulting to 25 records at a time if not provided... 21 | + Default: 25 22 | 23 | + Response 200 (application/json) 24 | Success 25 | + Attributes (ListBooksResponse) 26 | + Response 401 27 | Request failed. Received when a request is made with invalid API credentials... 28 | + Response 403 29 | Request failed. Received when a request is made with valid API credentials towards an API operation or resource you do not have access to. 30 | 31 | # Data Structures 32 | 33 | ## ListBooksResponse (object) 34 | A list of book summaries as a result of a list or filter request... 35 | 36 | ### Properties 37 | + `books` (array[BookSummary], optional) 38 | 39 | ## BookSummary (object) 40 | Summarizes a book that is stocked by the book store... 41 | 42 | ### Properties 43 | + `bookId` (string, optional) - An internal identifier, separate from the ISBN, that identifies the book within the inventory 44 | + `isbn` (string, optional) - The ISBN of the book 45 | + `title` (string, optional) - The book title, e.g. A Practical Approach to API Design 46 | + `authors` (array[BookAuthor], optional) 47 | 48 | ## BookAuthor (object) 49 | Represents a single author for a book. Since a book may have more than one author, ... 50 | 51 | ### Properties 52 | + `authorId` (string, optional) - An internal identifier that references the author 53 | + `fullName` (string, optional) - The full name of the author, e.g. D. Keith Casey 54 | 55 | -------------------------------------------------------------------------------- /description-format-examples/Docs-Example_v1.0.oas3.yaml: -------------------------------------------------------------------------------- 1 | openapi: 3.0.0 2 | info: 3 | title: Bookstore Shopping API Example 4 | description: The Bookstore Example REST-based API supports the shopping experience of an online bookstore. The API includes the following capabilities and operations... 5 | contact: { } 6 | version: '1.0' 7 | paths: 8 | /books: 9 | get: 10 | tags: 11 | - Books 12 | summary: Returns a paginated list of books 13 | description: Provides a paginated list of books based on the search criteria provided... 14 | operationId: ListBooks 15 | parameters: 16 | - name: q 17 | in: query 18 | description: A query string to use for filtering books by title and description. If not provided, all available books will be listed... 19 | schema: 20 | type: string 21 | responses: 22 | 200: 23 | description: Success 24 | headers: {} 25 | content: 26 | application/json: 27 | schema: 28 | $ref: '#/components/schemas/ListBooksResponse' 29 | 401: 30 | description: Request failed. Received when a request is made with invalid API credentials... 31 | 403: 32 | description: Request failed. Received when a request is made with valid API credentials towards an API operation or resource you do not have access to. 33 | deprecated: false 34 | components: 35 | schemas: 36 | ListBooksResponse: 37 | title: ListBooksResponse 38 | type: object 39 | properties: 40 | books: 41 | type: array 42 | items: 43 | $ref: '#/components/schemas/BookSummary' 44 | description: '' 45 | description: "A list of book summaries as a result of a list or filter request..." 46 | BookSummary: 47 | title: BookSummary 48 | type: object 49 | properties: 50 | bookId: 51 | type: string 52 | description: An internal identifier, separate from the ISBN, that identifies the book within the inventory 53 | isbn: 54 | type: string 55 | description: The ISBN of the book 56 | title: 57 | type: string 58 | description: The book title, e.g. A Practical Approach to API Design 59 | authors: 60 | type: array 61 | items: 62 | $ref: '#/components/schemas/BookAuthor' 63 | description: '' 64 | description: "Summarizes a book that is stocked by the book store..." 65 | BookAuthor: 66 | title: BookAuthor 67 | type: object 68 | properties: 69 | authorId: 70 | type: string 71 | description: An internal identifier that references the author 72 | fullName: 73 | type: string 74 | description: The full name of the author, e.g. D. Keith Casey 75 | description: "Represents a single author for a book. Since a book may have more than one author, ..." 76 | -------------------------------------------------------------------------------- /description-format-examples/Docs-Example_v1.0.raml10.yaml: -------------------------------------------------------------------------------- 1 | #%RAML 1.0 2 | title: Bookstore Shopping API Example 3 | version: 1.0 4 | baseUri: https://www.example.com 5 | baseUriParameters: 6 | defaultHost: 7 | required: false 8 | default: www.example.com 9 | example: 10 | value: www.example.com 11 | displayName: defaultHost 12 | type: string 13 | protocols: 14 | - HTTPS 15 | documentation: 16 | - title: Bookstore Shopping API Example 17 | content: The Bookstore Example REST-based API supports the shopping experience of an online bookstore. The API includes the following capabilities and operations... 18 | types: 19 | ListBooksResponse: 20 | displayName: ListBooksResponse 21 | description: A list of book summaries as a result of a list or filter request... 22 | type: object 23 | properties: 24 | books: 25 | required: false 26 | displayName: books 27 | type: array 28 | items: 29 | type: BookSummary 30 | BookSummary: 31 | displayName: BookSummary 32 | description: Summarizes a book that is stocked by the book store... 33 | type: object 34 | properties: 35 | bookId: 36 | required: false 37 | displayName: bookId 38 | description: An internal identifier, separate from the ISBN, that identifies the book within the inventory 39 | type: string 40 | isbn: 41 | required: false 42 | displayName: isbn 43 | description: The ISBN of the book 44 | type: string 45 | title: 46 | required: false 47 | displayName: title 48 | description: The book title, e.g. A Practical Approach to API Design 49 | type: string 50 | authors: 51 | required: false 52 | displayName: authors 53 | type: array 54 | items: 55 | type: BookAuthor 56 | BookAuthor: 57 | displayName: BookAuthor 58 | description: Represents a single author for a book. Since a book may have more than one author, ... 59 | type: object 60 | properties: 61 | authorId: 62 | required: false 63 | displayName: authorId 64 | description: An internal identifier that references the author 65 | type: string 66 | fullName: 67 | required: false 68 | displayName: fullName 69 | description: The full name of the author, e.g. D. Keith Casey 70 | type: string 71 | /books: 72 | get: 73 | displayName: ListBooks 74 | description: Provides a paginated list of books based on the search criteria provided... 75 | queryParameters: 76 | q: 77 | required: false 78 | displayName: q 79 | description: A query string to use for filtering books by title and description. If not provided, all available books will be listed... 80 | type: string 81 | offset: 82 | required: false 83 | default: 0 84 | example: 85 | value: 0 86 | displayName: offset 87 | description: A offset from which the list of books are retrieved, where an offset of 0 means the first page of results... 88 | type: integer 89 | minimum: 0 90 | format: int32 91 | limit: 92 | required: false 93 | default: 25 94 | example: 95 | value: 25 96 | displayName: limit 97 | description: Number of records to be included in API call, defaulting to 25 records at a time if not provided... 98 | type: integer 99 | minimum: 1 100 | maximum: 100 101 | format: int32 102 | headers: 103 | Authorization: 104 | required: true 105 | displayName: Authorization 106 | description: An OAuth 2.0 access token that authorizes your app to call this operation... 107 | type: string 108 | responses: 109 | 200: 110 | description: Success 111 | headers: 112 | Content-Type: 113 | default: application/json 114 | displayName: Content-Type 115 | type: string 116 | body: 117 | application/json: 118 | displayName: response 119 | description: Success 120 | type: ListBooksResponse 121 | 401: 122 | description: Request failed. Received when a request is made with invalid API credentials... 123 | body: {} 124 | 403: 125 | description: Request failed. Received when a request is made with valid API credentials towards an API operation or resource you do not have access to. 126 | body: {} 127 | -------------------------------------------------------------------------------- /bookstore/3a-design-rest/Shopping-API-REST.oas3.yaml: -------------------------------------------------------------------------------- 1 | openapi: 3.0.0 2 | info: 3 | title: Bookstore Shopping API - REST Example 4 | description: | 5 | Supports the shopping experience of an online bookstore, including browsing and searching for available books and shopping cart management. 6 | 7 | The Order Creation API is used to convert the shopping cart into an order that is prepared to accept shipping details, payment, and fulfillment tracking. 8 | 9 | The API includes the following shopping operations by capability: 10 | 11 | | Capability | Operation | 12 | |---------------------|-----------------------------------------| 13 | | List Recent Books | List Recent Books In Store | 14 | | List Recent Books | Search for a book by topic or keyword | 15 | | List Recent Books | View Book Details | 16 | | Place an Order | Create Cart | 17 | | Place an Order | Add Book to Cart | 18 | | Place an Order | Remove Book from the Cart | 19 | | Place an Order | Modify Book in Cart | 20 | | Place an Order | View Cart with Totals | 21 | 22 | contact: {} 23 | version: '1.0' 24 | servers: 25 | - url: https://{defaultHost} 26 | variables: 27 | defaultHost: 28 | default: www.example.com/shop 29 | paths: 30 | /books: 31 | get: 32 | tags: 33 | - Books 34 | summary: Returns a paginated list of available books 35 | description: "Returns a paginated list of available books based on the search criteria provided. If no search criteria is provided, books are returned in alphabetical order. \n" 36 | operationId: ListBooks 37 | parameters: 38 | - name: q 39 | in: query 40 | description: A query string to use for filtering books by title and description. If not provided, all available books will be listed. Note that the query argument 'q' is a common standard for general search queries 41 | style: form 42 | explode: true 43 | schema: 44 | type: string 45 | - name: daysSinceBookReleased 46 | in: query 47 | description: A query string to use for filtering books released within the last number of days, e.g. 7 means in the last 7 days. The default value of null indicates no time filtering is applied. Maximum number of days to filter is 30 days since today 48 | style: form 49 | explode: true 50 | schema: 51 | type: integer 52 | format: int32 53 | - name: offset 54 | in: query 55 | description: A offset from which the list of books are retrieved, where an offset of 0 means the first page of results. Default is an offset of 0 56 | style: form 57 | explode: true 58 | schema: 59 | minimum: 0 60 | type: integer 61 | format: int32 62 | default: 0 63 | - name: limit 64 | in: query 65 | description: Number of records to be included in API call, defaulting to 25 records at a time if not provided 66 | style: form 67 | explode: true 68 | schema: 69 | maximum: 100 70 | minimum: 1 71 | type: integer 72 | format: int32 73 | default: 25 74 | - name: Authorization 75 | in: header 76 | description: An OAuth 2.0 access token that authorizes your app to call this endpoint. For more information on how to obtain an access token, go to the "Getting Access" section. 77 | required: true 78 | style: simple 79 | schema: 80 | type: string 81 | - name: Client-Id 82 | in: header 83 | description: Client id consuming the api 84 | required: true 85 | style: simple 86 | schema: 87 | type: string 88 | - name: Content-Type 89 | in: header 90 | description: Content the client sends in request e.g. application/json. 91 | required: true 92 | style: simple 93 | schema: 94 | type: string 95 | - name: Client-Correlation-Id 96 | in: header 97 | description: It is an optional field that clients can provide to track traffic across different APIs. Clients who utilize this are responsible for generating the value, guaranteeing uniqueness, and providing it as a Header in every request. 98 | style: simple 99 | schema: 100 | type: string 101 | responses: 102 | 200: 103 | description: Success 104 | headers: {} 105 | content: 106 | application/json: 107 | schema: 108 | $ref: '#/components/schemas/ListBooksResponse' 109 | 401: 110 | description: Request failed, This is the response received when a request is made with invalid API credentials 111 | 403: 112 | description: Request failed, This is the response received when a request is made with valid API credentials towards an API endpoint or resource you do not have access to. 113 | deprecated: false 114 | /books/{bookId}: 115 | get: 116 | tags: 117 | - Books 118 | summary: Retrieves the full details about a book 119 | description: "Retrieves the full details about a book by the provided bookId. Details provided include: title, ISBN, plain text description, and the list of authors \n" 120 | operationId: ViewBookDetails 121 | parameters: 122 | - name: bookId 123 | in: path 124 | description: The book identifier to be retrieved 125 | required: true 126 | style: simple 127 | schema: 128 | type: string 129 | responses: 130 | 200: 131 | description: Success 132 | headers: {} 133 | content: 134 | application/json: 135 | schema: 136 | $ref: '#/components/schemas/BookDetails' 137 | 401: 138 | description: Request failed, This is the response received when a request is made with invalid API credentials 139 | 403: 140 | description: Request failed, This is the response received when a request is made with valid API credentials towards an API endpoint or resource you do not have access to. 141 | 404: 142 | description: Request failed, This is the response received when a request is made and there no data is found for the bookId path parameter. 143 | deprecated: false 144 | /carts/{cartId}: 145 | get: 146 | tags: 147 | - Carts 148 | summary: Retrieves the full details about a cart 149 | description: | 150 | Retrieves the full details about a cart by the provided identifier. Details provided include: the status of the cart, the list of books + quantities, and the total cost 151 | operationId: ViewCartDetails 152 | parameters: 153 | - name: cartId 154 | in: path 155 | description: The cart identifier to be retrieved 156 | required: true 157 | style: simple 158 | schema: 159 | type: string 160 | responses: 161 | 200: 162 | description: Success 163 | headers: {} 164 | content: 165 | application/json: 166 | schema: 167 | $ref: '#/components/schemas/CartDetails' 168 | 401: 169 | description: Request failed, This is the response received when a request is made with invalid API credentials 170 | 403: 171 | description: Request failed, This is the response received when a request is made with valid API credentials towards an API endpoint or resource you do not have access to. 172 | 404: 173 | description: Request failed, This is the response received when a request is made and there no data is found for the path parameter. 174 | deprecated: false 175 | /carts: 176 | post: 177 | tags: 178 | - Carts 179 | summary: Creates a new cart with a single item to begin the shopping process 180 | description: "Creates a new cart with a single item to begin the shopping process. The workflow allows the customer to add a quantity of books to the cart as cart items. These items may be manipulated directly prior to creating an order, similar to any online shopping cart experience. Once ready, use the CreateOrder operation to convert the cart into an order and apply payment.\n \n" 181 | operationId: CreateNewCart 182 | parameters: [] 183 | requestBody: 184 | description: '' 185 | content: 186 | application/json: 187 | schema: 188 | $ref: '#/components/schemas/NewCart' 189 | required: true 190 | responses: 191 | 201: 192 | description: Created 193 | headers: 194 | Location: 195 | description: Specifies the URL of the newly created resource 196 | content: 197 | text/plain: 198 | schema: 199 | type: string 200 | content: 201 | application/json: 202 | schema: 203 | $ref: '#/components/schemas/CartDetails' 204 | 400: 205 | description: Request failed, refer to Common HTTP 400 Response Body for details 206 | 401: 207 | description: Request failed, This is the response received when a request is made with invalid API credentials 208 | 403: 209 | description: Request failed, This is the response received when a request is made with valid API credentials towards an API endpoint or resource you do not have access to. 210 | 500: 211 | description: General server error, This is the response received when a request is made towards API but the API could not fulfill the request due to factors on the API side. 212 | deprecated: false 213 | /carts/{cartId}/items: 214 | post: 215 | tags: 216 | - CartItems 217 | summary: Adds a new Book to an existing Cart as a CartItem 218 | description: > 219 | Adds a new Book to an existing Cart as a CartItem, which includes the quantity of books desired. Recalculates the cart total, and returns the updated cart details 220 | operationId: AddBookToCart 221 | parameters: 222 | - name: cartId 223 | in: path 224 | description: The cart identifier to be retrieved 225 | required: true 226 | style: simple 227 | schema: 228 | type: string 229 | requestBody: 230 | description: '' 231 | content: 232 | application/json: 233 | schema: 234 | $ref: '#/components/schemas/NewCartItem' 235 | required: false 236 | responses: 237 | 201: 238 | description: Created 239 | headers: 240 | Location: 241 | description: Specifies the URL of the newly created resource 242 | content: 243 | text/plain: 244 | schema: 245 | type: string 246 | content: 247 | application/json: 248 | schema: 249 | $ref: '#/components/schemas/CartDetails' 250 | 401: 251 | description: Request failed, This is the response received when a request is made with invalid API credentials 252 | 403: 253 | description: Request failed, This is the response received when a request is made with valid API credentials towards an API endpoint or resource you do not have access to. 254 | 404: 255 | description: Request failed, This is the response received when a request is made and there no data is found for the path parameter. 256 | 409: 257 | description: Request failed due to the cart being marked as archived once it has been converted to an order and no longer editable 258 | deprecated: false 259 | /carts/{cartId}/items/{cartItemId}: 260 | patch: 261 | tags: 262 | - CartItems 263 | summary: Modifies the quantity of a CartItem in an existing Cart 264 | description: > 265 | Modifies the quantity of a CartItem in an existing Cart, recalculates the cart total, and returns the updated cart details. 266 | operationId: ModifyBookInCart 267 | parameters: 268 | - name: cartId 269 | in: path 270 | description: The Cart identifier to be retrieved 271 | required: true 272 | style: simple 273 | schema: 274 | type: string 275 | - name: cartItemId 276 | in: path 277 | description: The CartItem identifier to be retrieved 278 | required: true 279 | style: simple 280 | schema: 281 | type: string 282 | requestBody: 283 | description: '' 284 | content: 285 | application/json: 286 | schema: 287 | $ref: '#/components/schemas/ModifyCartItem' 288 | required: false 289 | responses: 290 | 200: 291 | description: Modified the cart item successfully. The updated cart is returned, including an updated cart total 292 | headers: {} 293 | content: 294 | application/json: 295 | schema: 296 | $ref: '#/components/schemas/CartDetails' 297 | 401: 298 | description: Request failed, This is the response received when a request is made with invalid API credentials 299 | 403: 300 | description: Request failed, This is the response received when a request is made with valid API credentials towards an API endpoint or resource you do not have access to. 301 | 404: 302 | description: Request failed, This is the response received when a request is made and there no data is found for the path parameter. 303 | 409: 304 | description: Request failed due to the cart being marked as archived once it has been converted to an order and no longer editable 305 | deprecated: false 306 | delete: 307 | tags: 308 | - CartItems 309 | summary: Removes a CartItem from an existing Cart 310 | description: "Removes a CartItem from an existing Cart, recalculates the cart total, and returns the updated cart details. Please note that since the cart has been recalculated and returned, the response code for a successful deletion of the cart item is a 200 rather than the default of a 204 when there is no response payload. \n" 311 | operationId: RemoveBookFromCart 312 | parameters: 313 | - name: cartId 314 | in: path 315 | description: The Cart identifier to be retrieved 316 | required: true 317 | style: simple 318 | schema: 319 | type: string 320 | - name: cartItemId 321 | in: path 322 | description: The CartItem identifier to be retrieved 323 | required: true 324 | style: simple 325 | schema: 326 | type: string 327 | responses: 328 | 200: 329 | description: Deleted the cart item successfully 330 | headers: {} 331 | content: 332 | application/json: 333 | schema: 334 | $ref: '#/components/schemas/CartDetails' 335 | 401: 336 | description: Request failed, This is the response received when a request is made with invalid API credentials 337 | 403: 338 | description: Request failed, This is the response received when a request is made with valid API credentials towards an API endpoint or resource you do not have access to. 339 | 404: 340 | description: Request failed, This is the response received when a request is made and there no data is found for the path parameter. 341 | 409: 342 | description: Request failed due to the cart being marked as archived once it has been converted to an order and no longer editable 343 | deprecated: false 344 | components: 345 | schemas: 346 | ListBooksResponse: 347 | title: ListBooksResponse 348 | type: object 349 | properties: 350 | books: 351 | type: array 352 | items: 353 | $ref: '#/components/schemas/BookSummary' 354 | description: '' 355 | description: "A list of book summaries as a result of a list or filter request. The following hypermedia links are offered:\n \n - next: (optional) indicates the next page of results is available\n - previous: (optional) indicates a previous page of results is available\n - self: a link to the current page of results\n - first: a link to the first page of results\n - last: a link to the last page of results" 356 | BookSummary: 357 | title: BookSummary 358 | type: object 359 | properties: 360 | bookId: 361 | type: string 362 | description: An internal identifier, separate from the ISBN, that identifies the book within the inventory 363 | isbn: 364 | type: string 365 | description: The ISBN of the book 366 | title: 367 | type: string 368 | description: The book title, e.g. A Practical Approach to API Design 369 | authors: 370 | type: array 371 | items: 372 | $ref: '#/components/schemas/BookAuthor' 373 | description: '' 374 | description: "Summarizes a book that is stocked by the book store. The following hypermedia links are offered:\n \n - bookDetails: link to fetch the book details" 375 | BookDetails: 376 | title: BookDetails 377 | type: object 378 | properties: 379 | bookId: 380 | type: string 381 | description: An internal identifier, separate from the ISBN, that identifies the book within the inventory 382 | isbn: 383 | type: string 384 | description: The ISBN of the book 385 | title: 386 | type: string 387 | description: The book title, e.g. A Practical Approach to API Design 388 | description: 389 | type: string 390 | description: A description of the book in plain text format 391 | authors: 392 | type: array 393 | items: 394 | $ref: '#/components/schemas/BookAuthor' 395 | description: '' 396 | description: "Details about a book that is stocked by the book store. The following hypermedia links are offered:\n \n - self: link to fetch the book details" 397 | BookAuthor: 398 | title: BookAuthor 399 | type: object 400 | properties: 401 | authorId: 402 | type: string 403 | description: An internal identifier that references the author 404 | fullName: 405 | type: string 406 | description: The full name of the author, e.g. D. Keith Casey 407 | description: "Represents a single author for a book. Since a book may have more than one author, books will contain an array of BookAuthors. The following hypermedia links are offered:\n \n - self: link to fetch the author details" 408 | CartItem: 409 | title: CartItem 410 | type: object 411 | properties: 412 | cartItemId: 413 | type: string 414 | description: An internal identifier for the cart item inside the cart 415 | bookId: 416 | type: string 417 | description: The book that is being referenced within the order 418 | title: 419 | type: string 420 | description: The book title, e.g. A Practical Approach to API Design 421 | quantity: 422 | minimum: 1 423 | type: integer 424 | description: The number of copies of the book requested 425 | format: int32 426 | description: "Captures a book with the quantity desired in a cart. The following hypermedia links are offered:\n \n - self: link to fetch the cart item details\n - bookDetails: link to fetch the book details" 427 | NewCart: 428 | title: NewCart 429 | required: 430 | - bookId 431 | - quantity 432 | type: object 433 | properties: 434 | bookId: 435 | type: string 436 | description: The book that is being added to the cart 437 | quantity: 438 | minimum: 1 439 | type: integer 440 | description: The number of copies of the book to be added to the cart 441 | format: int32 442 | description: Creates a new cart with the initial cart item added 443 | NewCartItem: 444 | title: NewCartItem 445 | required: 446 | - bookId 447 | - quantity 448 | type: object 449 | properties: 450 | bookId: 451 | type: string 452 | description: The book that is being added to the cart 453 | quantity: 454 | minimum: 1 455 | type: integer 456 | description: The number of copies of the book to be added to the cart 457 | format: int32 458 | description: Specifies a book and quantity to add to a cart 459 | ModifyCartItem: 460 | title: ModifyCartItem 461 | required: 462 | - quantity 463 | type: object 464 | properties: 465 | quantity: 466 | minimum: 1 467 | type: integer 468 | description: The number of copies of the book to adjust the cart item to 469 | format: int32 470 | description: Modifies an existing cart item's quantity 471 | CartDetails: 472 | title: CartDetails 473 | type: object 474 | properties: 475 | cartId: 476 | type: string 477 | description: An internal identifier for the cart 478 | items: 479 | type: array 480 | items: 481 | $ref: '#/components/schemas/CartItem' 482 | description: '' 483 | totalCostInCents: 484 | minimum: 0 485 | type: integer 486 | description: The total cost of the cart 487 | format: int32 488 | cartStatus: 489 | $ref: '#/components/schemas/CartStatus' 490 | description: Contains the full list of books and quantities contained within the cart, along with the total cost of the cart 491 | CartStatus: 492 | title: CartStatus 493 | enum: 494 | - Active 495 | - Converted 496 | - Abandoned 497 | type: string 498 | description: The current status of the cart 499 | -------------------------------------------------------------------------------- /bookstore/3a-design-rest/Order-Creation-API-REST.oas3.yaml: -------------------------------------------------------------------------------- 1 | openapi: 3.0.0 2 | info: 3 | title: Bookstore Shopping Cart API - REST Example 4 | description: | 5 | The Bookstore Example API supports the shopping experience of an online bookstore. The API includes the following operations by capability: 6 | 7 | | Capability | Operation | 8 | |---------------------|-----------------------------------------| 9 | | List Recent Books | List Recent Books In Store | 10 | | List Recent Books | Search for a book by topic or keyword | 11 | | List Recent Books | View Book Details | 12 | | Place an Order | Create Cart | 13 | | Place an Order | Add Book to Cart | 14 | | Place an Order | Remove Book from the Cart | 15 | | Place an Order | Modify Book in Cart | 16 | | Place an Order | View Cart with Totals | 17 | 18 | contact: {} 19 | version: '1.0' 20 | servers: 21 | - url: https://{defaultHost} 22 | variables: 23 | defaultHost: 24 | default: www.example.com/enterprise/shop 25 | paths: 26 | /books: 27 | get: 28 | tags: 29 | - Books 30 | summary: ListBooks 31 | description: "Provides a paginated list of books based on the search criteria provided. If no search criteria is provided, books are returned in alphabetical order. \n" 32 | operationId: ListBooks 33 | parameters: 34 | - name: q 35 | in: query 36 | description: A query string to use for filtering books by title and description. If not provided, all available books will be listed. Note that the query argument 'q' is a common standard for general search queries 37 | style: form 38 | explode: true 39 | schema: 40 | type: string 41 | - name: daysSinceBookReleased 42 | in: query 43 | description: A query string to use for filtering books released within the last number of days, e.g. 7 means in the last 7 days. The default value of null indicates no time filtering is applied. Maximum number of days to filter is 30 days since today 44 | style: form 45 | explode: true 46 | schema: 47 | type: integer 48 | format: int32 49 | - name: offset 50 | in: query 51 | description: A offset from which the list of books are retrieved, where an offset of 0 means the first page of results. Default is an offset of 0 52 | style: form 53 | explode: true 54 | schema: 55 | minimum: 0 56 | type: integer 57 | format: int32 58 | default: 0 59 | - name: limit 60 | in: query 61 | description: Number of records to be included in API call, defaulting to 25 records at a time if not provided 62 | style: form 63 | explode: true 64 | schema: 65 | maximum: 100 66 | minimum: 1 67 | type: integer 68 | format: int32 69 | default: 25 70 | - name: Authorization 71 | in: header 72 | description: An OAuth 2.0 access token that authorizes your app to call this endpoint. For more information on how to obtain an access token, go to the "Getting Access" section. 73 | required: true 74 | style: simple 75 | schema: 76 | type: string 77 | - name: Client-Id 78 | in: header 79 | description: Client id consuming the api 80 | required: true 81 | style: simple 82 | schema: 83 | type: string 84 | - name: Content-Type 85 | in: header 86 | description: Content the client sends in request e.g. application/json. 87 | required: true 88 | style: simple 89 | schema: 90 | type: string 91 | - name: Client-Correlation-Id 92 | in: header 93 | description: It is an optional field that clients can provide to track traffic across different APIs. Clients who utilize this are responsible for generating the value, guaranteeing uniqueness, and providing it as a Header in every request. 94 | style: simple 95 | schema: 96 | type: string 97 | responses: 98 | 200: 99 | description: Success 100 | headers: {} 101 | content: 102 | application/json: 103 | schema: 104 | $ref: '#/components/schemas/ListBooksResponse' 105 | 401: 106 | description: Request failed, This is the response received when a request is made with invalid API credentials 107 | 403: 108 | description: Request failed, This is the response received when a request is made with valid API credentials towards an API endpoint or resource you do not have access to. 109 | deprecated: false 110 | /books/{bookId}: 111 | get: 112 | tags: 113 | - Books 114 | summary: ViewBookDetails 115 | description: "Retrieves the full details about a book by the provided bookId. Details provided include: title, ISBN, plain text description, and the list of authors \n" 116 | operationId: ViewBookDetails 117 | parameters: 118 | - name: bookId 119 | in: path 120 | description: The book identifier to be retrieved 121 | required: true 122 | style: simple 123 | schema: 124 | type: string 125 | responses: 126 | 200: 127 | description: Success 128 | headers: {} 129 | content: 130 | application/json: 131 | schema: 132 | $ref: '#/components/schemas/BookDetails' 133 | 401: 134 | description: Request failed, This is the response received when a request is made with invalid API credentials 135 | 403: 136 | description: Request failed, This is the response received when a request is made with valid API credentials towards an API endpoint or resource you do not have access to. 137 | 404: 138 | description: Request failed, This is the response received when a request is made and there no data is found for the bookId path parameter. 139 | deprecated: false 140 | /carts/{cartId}: 141 | get: 142 | tags: 143 | - Carts 144 | summary: ViewCartDetails 145 | description: > 146 | Retrieves the full details about a cart by the provided identifier. Details provided include: the status of the cart, the list of books + quantities, and the total cost 147 | operationId: ViewCartDetails 148 | parameters: 149 | - name: cartId 150 | in: path 151 | description: The cart identifier to be retrieved 152 | required: true 153 | style: simple 154 | schema: 155 | type: string 156 | responses: 157 | 200: 158 | description: Success 159 | headers: {} 160 | content: 161 | application/json: 162 | schema: 163 | $ref: '#/components/schemas/CartDetails' 164 | 401: 165 | description: Request failed, This is the response received when a request is made with invalid API credentials 166 | 403: 167 | description: Request failed, This is the response received when a request is made with valid API credentials towards an API endpoint or resource you do not have access to. 168 | 404: 169 | description: Request failed, This is the response received when a request is made and there no data is found for the path parameter. 170 | deprecated: false 171 | /orders/{orderId}: 172 | get: 173 | tags: 174 | - Orders 175 | summary: ViewOrderDetails 176 | description: > 177 | Retrieves the full details about an order by the provided orderId. Details provided include: the status of the order, the list of books + quantities, and the total cost 178 | operationId: ViewOrderDetails 179 | parameters: 180 | - name: orderId 181 | in: path 182 | description: The order identifier to be retrieved 183 | required: true 184 | style: simple 185 | schema: 186 | type: string 187 | responses: 188 | 200: 189 | description: Success 190 | headers: {} 191 | content: 192 | application/json: 193 | schema: 194 | $ref: '#/components/schemas/OrderDetails' 195 | 401: 196 | description: Request failed, This is the response received when a request is made with invalid API credentials 197 | 403: 198 | description: Request failed, This is the response received when a request is made with valid API credentials towards an API endpoint or resource you do not have access to. 199 | 404: 200 | description: Request failed, This is the response received when a request is made and there no data is found for the path parameter. 201 | deprecated: false 202 | /carts: 203 | post: 204 | tags: 205 | - Carts 206 | summary: CreateNewCart 207 | description: "Creates a new cart with a single item to begin the shopping process. The workflow allows the customer to add a quantity of books to the cart as cart items. These items may be manipulated directly prior to creating an order, similar to any online shopping cart experience. Once ready, use the CreateOrder operation to convert the cart into an order and apply payment.\n \n" 208 | operationId: CreateNewCart 209 | parameters: [] 210 | requestBody: 211 | description: '' 212 | content: 213 | application/json: 214 | schema: 215 | $ref: '#/components/schemas/NewCart' 216 | required: true 217 | responses: 218 | 201: 219 | description: Created 220 | headers: 221 | Location: 222 | description: Specifies the URL of the newly created resource 223 | content: 224 | text/plain: 225 | schema: 226 | type: string 227 | content: 228 | application/json: 229 | schema: 230 | $ref: '#/components/schemas/CartDetails' 231 | 400: 232 | description: Request failed, refer to Common HTTP 400 Response Body for details 233 | 401: 234 | description: Request failed, This is the response received when a request is made with invalid API credentials 235 | 403: 236 | description: Request failed, This is the response received when a request is made with valid API credentials towards an API endpoint or resource you do not have access to. 237 | 500: 238 | description: General server error, This is the response received when a request is made towards API but the API could not fulfill the request due to factors on the API side. 239 | deprecated: false 240 | /carts/{cartId}/items: 241 | post: 242 | tags: 243 | - CartItems 244 | summary: AddBookToCart 245 | description: > 246 | Adds a new Book to an existing Cart as a CartItem, which includes the quantity of books desired. Recalculates the cart total, and returns the updated cart details 247 | operationId: AddBookToCart 248 | parameters: 249 | - name: cartId 250 | in: path 251 | description: The cart identifier to be retrieved 252 | required: true 253 | style: simple 254 | schema: 255 | type: string 256 | requestBody: 257 | description: '' 258 | content: 259 | application/json: 260 | schema: 261 | $ref: '#/components/schemas/NewCartItem' 262 | required: false 263 | responses: 264 | 201: 265 | description: Created 266 | headers: 267 | Location: 268 | description: Specifies the URL of the newly created resource 269 | content: 270 | text/plain: 271 | schema: 272 | type: string 273 | content: 274 | application/json: 275 | schema: 276 | $ref: '#/components/schemas/CartDetails' 277 | 401: 278 | description: Request failed, This is the response received when a request is made with invalid API credentials 279 | 403: 280 | description: Request failed, This is the response received when a request is made with valid API credentials towards an API endpoint or resource you do not have access to. 281 | 404: 282 | description: Request failed, This is the response received when a request is made and there no data is found for the path parameter. 283 | 409: 284 | description: Request failed due to the cart being marked as archived once it has been converted to an order and no longer editable 285 | deprecated: false 286 | /carts/{cartId}/items/{cartItemId}: 287 | patch: 288 | tags: 289 | - CartItems 290 | summary: ModifyBookInCart 291 | description: > 292 | Modifies the quantity of a CartItem in an existing Cart, recalculates the cart total, and returns the updated cart details. 293 | operationId: ModifyBookInCart 294 | parameters: 295 | - name: cartId 296 | in: path 297 | description: The Cart identifier to be retrieved 298 | required: true 299 | style: simple 300 | schema: 301 | type: string 302 | - name: cartItemId 303 | in: path 304 | description: The CartItem identifier to be retrieved 305 | required: true 306 | style: simple 307 | schema: 308 | type: string 309 | requestBody: 310 | description: '' 311 | content: 312 | application/json: 313 | schema: 314 | $ref: '#/components/schemas/ModifyCartItem' 315 | required: false 316 | responses: 317 | 200: 318 | description: Modified the cart item successfully. The updated cart is returned, including an updated cart total 319 | headers: {} 320 | content: 321 | application/json: 322 | schema: 323 | $ref: '#/components/schemas/CartDetails' 324 | 401: 325 | description: Request failed, This is the response received when a request is made with invalid API credentials 326 | 403: 327 | description: Request failed, This is the response received when a request is made with valid API credentials towards an API endpoint or resource you do not have access to. 328 | 404: 329 | description: Request failed, This is the response received when a request is made and there no data is found for the path parameter. 330 | 409: 331 | description: Request failed due to the cart being marked as archived once it has been converted to an order and no longer editable 332 | deprecated: false 333 | delete: 334 | tags: 335 | - CartItems 336 | summary: RemoveBookFromCart 337 | description: "Removes a CartItem from an existing Cart, recalculates the cart total, and returns the updated cart details. Please note that since the cart has been recalculated and returned, the response code for a successful deletion of the cart item is a 200 rather than the default of a 204 when there is no response payload. \n" 338 | operationId: RemoveBookFromCart 339 | parameters: 340 | - name: cartId 341 | in: path 342 | description: The Cart identifier to be retrieved 343 | required: true 344 | style: simple 345 | schema: 346 | type: string 347 | - name: cartItemId 348 | in: path 349 | description: The CartItem identifier to be retrieved 350 | required: true 351 | style: simple 352 | schema: 353 | type: string 354 | responses: 355 | 200: 356 | description: Deleted the cart item successfully 357 | headers: {} 358 | content: 359 | application/json: 360 | schema: 361 | $ref: '#/components/schemas/CartDetails' 362 | 401: 363 | description: Request failed, This is the response received when a request is made with invalid API credentials 364 | 403: 365 | description: Request failed, This is the response received when a request is made with valid API credentials towards an API endpoint or resource you do not have access to. 366 | 404: 367 | description: Request failed, This is the response received when a request is made and there no data is found for the path parameter. 368 | 409: 369 | description: Request failed due to the cart being marked as archived once it has been converted to an order and no longer editable 370 | deprecated: false 371 | /orders: 372 | post: 373 | tags: 374 | - Orders 375 | summary: CreateNewOrder 376 | description: "Creates a new order based upon an existing cart's contents. The status is initially set to 'New' until full payment has been applied. \n \n" 377 | operationId: CreateNewOrder 378 | parameters: [] 379 | requestBody: 380 | description: '' 381 | content: 382 | application/json: 383 | schema: 384 | $ref: '#/components/schemas/NewOrder' 385 | required: true 386 | responses: 387 | 201: 388 | description: Created 389 | headers: 390 | Location: 391 | description: Specifies the URL of the newly created resource 392 | content: 393 | text/plain: 394 | schema: 395 | type: string 396 | content: 397 | application/json: 398 | schema: 399 | $ref: '#/components/schemas/OrderDetails' 400 | 400: 401 | description: Request failed, refer to Common HTTP 400 Response Body for details 402 | 401: 403 | description: Request failed, This is the response received when a request is made with invalid API credentials 404 | 403: 405 | description: Request failed, This is the response received when a request is made with valid API credentials towards an API endpoint or resource you do not have access to. 406 | 500: 407 | description: General server error, This is the response received when a request is made towards API but the API could not fulfill the request due to factors on the API side. 408 | deprecated: false 409 | /orders/{orderId}/cancel: 410 | post: 411 | tags: 412 | - Books 413 | summary: CancelOrder 414 | description: "Attempts to cancel an order. If the order is in a valid state for a refund, a refund will be scheduled. If the order hasn't been paid for, the order will be marked as cancelled and may no longer be changed.\n\nNote that this could be used in a PATCH to set the status of an order to cancelled. However, providing this functional endpoint allows for different access control to this endpoint (path + verb), e.g. support staff only, whereas using a PATCH would require enforcing access controls within the endpoint implementation itself. \n" 415 | operationId: CancelOrder 416 | parameters: 417 | - name: orderId 418 | in: path 419 | description: The order identifier to be retrieved 420 | required: true 421 | style: simple 422 | schema: 423 | type: string 424 | responses: 425 | 200: 426 | description: Success 427 | headers: {} 428 | content: 429 | application/json: 430 | schema: 431 | $ref: '#/components/schemas/OrderDetails' 432 | 401: 433 | description: Request failed, This is the response received when a request is made with invalid API credentials 434 | 403: 435 | description: Request failed, This is the response received when a request is made with valid API credentials towards an API endpoint or resource you do not have access to. 436 | 404: 437 | description: Request failed, This is the response received when a request is made and there no data is found for the path parameter. 438 | deprecated: false 439 | /orders/{orderId}/payments: 440 | post: 441 | tags: 442 | - OrderPayments 443 | summary: SubmitPaymentDetailsForOrder 444 | description: > 445 | Adds a partial or full credit card payment to the Order. Once verified, the payment will be assigned a status of 'success' or 'failed' based on the transaction result and returned 446 | operationId: SubmitPaymentDetailsForOrder 447 | parameters: 448 | - name: orderId 449 | in: path 450 | description: The order identifier to be retrieved 451 | required: true 452 | style: simple 453 | schema: 454 | type: string 455 | requestBody: 456 | description: '' 457 | content: 458 | application/json: 459 | schema: 460 | $ref: '#/components/schemas/NewOrderPayment' 461 | required: false 462 | responses: 463 | 201: 464 | description: Created 465 | headers: 466 | Location: 467 | description: Specifies the URL of the newly created resource 468 | content: 469 | text/plain: 470 | schema: 471 | type: string 472 | content: 473 | application/json: 474 | schema: 475 | $ref: '#/components/schemas/OrderPaymentDetails' 476 | 401: 477 | description: Request failed, This is the response received when a request is made with invalid API credentials 478 | 403: 479 | description: Request failed, This is the response received when a request is made with valid API credentials towards an API endpoint or resource you do not have access to. 480 | 404: 481 | description: Request failed, This is the response received when a request is made and there no data is found for the path parameter. 482 | deprecated: false 483 | components: 484 | schemas: 485 | ListBooksResponse: 486 | title: ListBooksResponse 487 | type: object 488 | properties: 489 | books: 490 | type: array 491 | items: 492 | $ref: '#/components/schemas/BookSummary' 493 | description: '' 494 | description: "A list of book summaries as a result of a list or filter request. The following hypermedia links are offered:\n \n - next: (optional) indicates the next page of results is available\n - previous: (optional) indicates a previous page of results is available\n - self: a link to the current page of results\n - first: a link to the first page of results\n - last: a link to the last page of results" 495 | BookSummary: 496 | title: BookSummary 497 | type: object 498 | properties: 499 | bookId: 500 | type: string 501 | description: An internal identifier, separate from the ISBN, that identifies the book within the inventory 502 | isbn: 503 | type: string 504 | description: The ISBN of the book 505 | title: 506 | type: string 507 | description: The book title, e.g. A Practical Approach to API Design 508 | authors: 509 | type: array 510 | items: 511 | $ref: '#/components/schemas/BookAuthor' 512 | description: '' 513 | description: "Summarizes a book that is stocked by the book store. The following hypermedia links are offered:\n \n - bookDetails: link to fetch the book details" 514 | BookDetails: 515 | title: BookDetails 516 | type: object 517 | properties: 518 | bookId: 519 | type: string 520 | description: An internal identifier, separate from the ISBN, that identifies the book within the inventory 521 | isbn: 522 | type: string 523 | description: The ISBN of the book 524 | title: 525 | type: string 526 | description: The book title, e.g. A Practical Approach to API Design 527 | description: 528 | type: string 529 | description: A description of the book in plain text format 530 | authors: 531 | type: array 532 | items: 533 | $ref: '#/components/schemas/BookAuthor' 534 | description: '' 535 | description: "Details about a book that is stocked by the book store. The following hypermedia links are offered:\n \n - self: link to fetch the book details" 536 | BookAuthor: 537 | title: BookAuthor 538 | type: object 539 | properties: 540 | authorId: 541 | type: string 542 | description: An internal identifier that references the author 543 | fullName: 544 | type: string 545 | description: The full name of the author, e.g. D. Keith Casey 546 | description: "Represents a single author for a book. Since a book may have more than one author, books will contain an array of BookAuthors. The following hypermedia links are offered:\n \n - self: link to fetch the author details" 547 | CartItem: 548 | title: CartItem 549 | type: object 550 | properties: 551 | cartItemId: 552 | type: string 553 | description: An internal identifier for the cart item inside the cart 554 | bookId: 555 | type: string 556 | description: The book that is being referenced within the order 557 | title: 558 | type: string 559 | description: The book title, e.g. A Practical Approach to API Design 560 | quantity: 561 | minimum: 1 562 | type: integer 563 | description: The number of copies of the book requested 564 | format: int32 565 | description: "Captures a book with the quantity desired in a cart. The following hypermedia links are offered:\n \n - self: link to fetch the cart item details\n - bookDetails: link to fetch the book details" 566 | NewCart: 567 | title: NewCart 568 | required: 569 | - bookId 570 | - quantity 571 | type: object 572 | properties: 573 | bookId: 574 | type: string 575 | description: The book that is being added to the cart 576 | quantity: 577 | minimum: 1 578 | type: integer 579 | description: The number of copies of the book to be added to the cart 580 | format: int32 581 | description: Creates a new cart with the initial cart item added 582 | NewCartItem: 583 | title: NewCartItem 584 | required: 585 | - bookId 586 | - quantity 587 | type: object 588 | properties: 589 | bookId: 590 | type: string 591 | description: The book that is being added to the cart 592 | quantity: 593 | minimum: 1 594 | type: integer 595 | description: The number of copies of the book to be added to the cart 596 | format: int32 597 | description: Specifies a book and quantity to add to a cart 598 | ModifyCartItem: 599 | title: ModifyCartItem 600 | required: 601 | - quantity 602 | type: object 603 | properties: 604 | quantity: 605 | minimum: 1 606 | type: integer 607 | description: The number of copies of the book to adjust the cart item to 608 | format: int32 609 | description: Modifies an existing cart item's quantity 610 | CartDetails: 611 | title: CartDetails 612 | type: object 613 | properties: 614 | cartId: 615 | type: string 616 | description: An internal identifier for the cart 617 | items: 618 | type: array 619 | items: 620 | $ref: '#/components/schemas/CartItem' 621 | description: '' 622 | totalCostInCents: 623 | minimum: 0 624 | type: integer 625 | description: The total cost of the cart 626 | format: int32 627 | cartStatus: 628 | $ref: '#/components/schemas/CartStatus' 629 | description: Contains the full list of books and quantities contained within the cart, along with the total cost of the cart 630 | NewOrder: 631 | title: NewOrder 632 | required: 633 | - cartId 634 | type: object 635 | properties: 636 | cartId: 637 | type: string 638 | description: The cart to convert to an order 639 | description: Creates a new order using the existing cart 640 | NewOrderPayment: 641 | title: NewOrderPayment 642 | required: 643 | - creditCardNumber 644 | - ccv 645 | - nameOnCard 646 | - amountInCents 647 | type: object 648 | properties: 649 | creditCardNumber: 650 | type: string 651 | description: The credit card number 652 | ccv: 653 | type: string 654 | description: The credit card verification number 655 | nameOnCard: 656 | type: string 657 | description: The name on the credit card, as it appears 658 | amountInCents: 659 | minimum: 1 660 | type: integer 661 | description: The amount to apply to the payment, in cents 662 | format: int32 663 | description: Captures the payment details for an order 664 | OrderDetails: 665 | title: OrderDetails 666 | type: object 667 | properties: 668 | orderId: 669 | type: string 670 | description: An internal identifier that references the order 671 | orderStatus: 672 | $ref: '#/components/schemas/OrderStatus' 673 | totalCostInCents: 674 | minimum: 0 675 | type: integer 676 | description: The total cost of the order 677 | format: int32 678 | items: 679 | type: array 680 | items: 681 | $ref: '#/components/schemas/CartItem' 682 | description: '' 683 | payments: 684 | type: array 685 | items: 686 | $ref: '#/components/schemas/OrderPaymentDetails' 687 | description: '' 688 | description: "Contains the full list of books and quantities contained within the order, along with the total cost of the order. The following hypermedia links are offered:\n \n - self: link to this order" 689 | OrderPaymentDetails: 690 | title: OrderPaymentDetails 691 | type: object 692 | properties: 693 | orderPaymentId: 694 | type: string 695 | description: An internal identifier that references the payment for an order 696 | creditCardLastFourDigits: 697 | type: string 698 | description: The last four digits of the credit card number 699 | paymentStatus: 700 | $ref: '#/components/schemas/PaymentStatus' 701 | amountInCents: 702 | type: integer 703 | description: The amount applied to the payment, in cents, or 0 if the payment failed 704 | format: int32 705 | description: "Summarizies the payment details for an order. The following hypermedia links are offered:\n \n - self: link to this order payment\n - orderDetails: link to the order this payment is attached to" 706 | CartStatus: 707 | title: CartStatus 708 | enum: 709 | - Active 710 | - Converted 711 | - Abandoned 712 | type: string 713 | description: The current status of the cart 714 | OrderStatus: 715 | title: OrderStatus 716 | enum: 717 | - New 718 | - Paid 719 | - Preparing 720 | - Prepared 721 | - Shipped 722 | - Received 723 | - Cancelled 724 | type: string 725 | description: The current status of the order 726 | PaymentStatus: 727 | title: PaymentStatus 728 | enum: 729 | - Success 730 | - Failed 731 | type: string 732 | description: Indicates if the credit card payment was successful or failed 733 | --------------------------------------------------------------------------------