Created
October 10, 2024 17:02
-
-
Save kinlane/83f5e2c36dada98b21c04ad03c71c9e9 to your computer and use it in GitHub Desktop.
JSON:API OpenAPI
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| openapi: 3.0.0 | |
| info: | |
| title: JSON:API OpenAPI | |
| description: A base OpenAPI for the JSON:API to be used as seed for new APIs. | |
| version: 1.0.0 | |
| tags: | |
| - name: Resources | |
| description: An array of JSON:API resources. | |
| paths: | |
| /resources: | |
| get: | |
| summary: Get Resources | |
| description: Returns a list of JSON:API resources. | |
| operationId: getResources | |
| tags: | |
| - Resources | |
| responses: | |
| '200': | |
| description: A array of resources. | |
| content: | |
| application/vnd.api+json: | |
| schema: | |
| $ref: '#/components/schemas/Resources' | |
| examples: | |
| sparse-fieldsets: | |
| $ref: '#/components/examples/ConfirmationSuccess' | |
| components: | |
| examples: | |
| ConfirmationSuccess: | |
| summary: Sparse Fields | |
| description: Uses the default Sparse Fields example at - https://jsonapi.org/examples/#sparse-fieldsets. | |
| value: | |
| data: | |
| - type: articles | |
| id: '1' | |
| attributes: | |
| title: JSON:API paints my bikeshed! | |
| body: The shortest article. Ever. | |
| created: '2015-05-22T14:56:29.000Z' | |
| updated: '2015-05-22T14:56:28.000Z' | |
| relationships: | |
| author: | |
| data: | |
| id: '42' | |
| type: people | |
| included: | |
| - type: people | |
| id: '42' | |
| attributes: | |
| name: John | |
| age: 80 | |
| gender: male | |
| PaginationSuccess: | |
| summary: Pagination | |
| description: Uses the Pagination example at - https://jsonapi.org/examples/#pagination. | |
| value: | |
| meta: | |
| totalPages: 13 | |
| data: | |
| - type: articles | |
| id: '3' | |
| attributes: | |
| title: JSON:API paints my bikeshed! | |
| body: The shortest article. Ever. | |
| created: '2015-05-22T14:56:29.000Z' | |
| updated: '2015-05-22T14:56:28.000Z' | |
| links: | |
| self: http://example.com/articles?page[number]=3&page[size]=1 | |
| first: http://example.com/articles?page[number]=1&page[size]=1 | |
| prev: http://example.com/articles?page[number]=2&page[size]=1 | |
| next: http://example.com/articles?page[number]=4&page[size]=1 | |
| last: http://example.com/articles?page[number]=13&page[size]=1 | |
| schemas: | |
| Resources: | |
| type: array | |
| items: | |
| $ref: '#/components/schemas/Resource' | |
| Resource: | |
| description: 'Resource objects appear in a JSON:API document to represent resource.' | |
| type: object | |
| required: | |
| - type | |
| - id | |
| properties: | |
| type: | |
| type: string | |
| id: | |
| type: string | |
| attributes: | |
| "$ref": "#/components/schemas/Attributes" | |
| relationships: | |
| "$ref": "#/components/schemas/Relationships" | |
| links: | |
| "$ref": "#/components/schemas/Links" | |
| meta: | |
| "$ref": "#/components/schemas/Meta" | |
| data: | |
| "$ref": "#/components/schemas/Data" | |
| pagination: | |
| "$ref": "#/components/schemas/Pagination" | |
| additionalProperties: false | |
| Meta: | |
| description: Non-standard meta-information that can not be represented as an attribute | |
| or relationship. | |
| type: object | |
| additionalProperties: true | |
| Data: | |
| description: The document's "primary data" is a representation of the resource | |
| or collection of resources targeted by a request. | |
| oneOf: | |
| - "$ref": "#/components/schemas/Resource" | |
| - description: An array of resource objects, an array of resource identifier objects, | |
| or an empty array ([]), for requests that target resource collections. | |
| type: array | |
| items: | |
| "$ref": "#/components/schemas/Resource" | |
| uniqueItems: true | |
| - description: null if the request is one that might correspond to a single resource, | |
| but doesn't currently. | |
| type: 'null' | |
| RelationshipLinks: | |
| description: A resource object **MAY** contain references to other resource objects | |
| ("relationships"). Relationships may be to-one or to-many. Relationships can | |
| be specified by including a member in a resource's links object. | |
| type: object | |
| properties: | |
| self: | |
| description: A `self` member, whose value is a URL for the relationship itself | |
| (a "relationship URL"). This URL allows the client to directly manipulate | |
| the relationship. For example, it would allow a client to remove an `author` | |
| from an `article` without deleting the people resource itself. | |
| "$ref": "#/components/schemas/Link" | |
| related: | |
| "$ref": "#/components/schemas/Link" | |
| additionalProperties: true | |
| Links: | |
| type: object | |
| additionalProperties: | |
| "$ref": "#/components/schemas/Link" | |
| Link: | |
| description: 'A link **MUST** be represented as either: a string containing the | |
| link''s URL or a link object.' | |
| oneOf: | |
| - description: A string containing the link's URL. | |
| type: string | |
| format: uri-reference | |
| - description: A string containing the link's URL. | |
| type: string | |
| format: uri-reference | |
| Attributes: | |
| description: Members of the attributes object ("attributes") represent information | |
| about the resource object in which it's defined. | |
| type: object | |
| patternProperties: | |
| "^(?!relationships$|links$|id$|type$)\\w[-\\w_]*$": | |
| description: Attributes may contain any valid JSON value. | |
| additionalProperties: false | |
| Relationships: | |
| description: Members of the relationships object ("relationships") represent references | |
| from the resource object in which it's defined to other resource objects. | |
| type: object | |
| patternProperties: | |
| "^(?!id$|type$)\\w[-\\w_]*$": | |
| properties: | |
| links: | |
| "$ref": "#/components/schemas/RelationshipLinks" | |
| data: | |
| description: Member, whose value represents "resource linkage". | |
| oneOf: | |
| - "$ref": "#/components/schemas/RelationshipToOne" | |
| - "$ref": "#/components/schemas/RelationshipToMany" | |
| meta: | |
| "$ref": "#/components/schemas/Meta" | |
| anyOf: | |
| - required: | |
| - data | |
| - required: | |
| - meta | |
| - required: | |
| - links | |
| additionalProperties: false | |
| additionalProperties: false | |
| RelationshipToOne: | |
| description: References to other resource objects in a to-one ("relationship"). | |
| Relationships can be specified by including a member in a resource's links object. | |
| anyOf: | |
| - "$ref": "#/components/schemas/Empty" | |
| - "$ref": "#/components/schemas/Linkage" | |
| RelationshipToMany: | |
| description: An array of objects each containing "type" and "id" members for to-many | |
| relationships. | |
| type: array | |
| items: | |
| "$ref": "#/components/schemas/Linkage" | |
| uniqueItems: true | |
| Empty: | |
| description: Describes an empty to-one relationship. | |
| type: 'null' | |
| Linkage: | |
| description: The "type" and "id" to non-empty members. | |
| type: object | |
| required: | |
| - type | |
| - id | |
| properties: | |
| type: | |
| type: string | |
| id: | |
| type: string | |
| meta: | |
| "$ref": "#/components/schemas/Meta" | |
| additionalProperties: false | |
| Pagination: | |
| type: object | |
| properties: | |
| first: | |
| description: The first page of data | |
| oneOf: | |
| - type: string | |
| format: uri-reference | |
| - type: 'null' | |
| last: | |
| description: The last page of data | |
| oneOf: | |
| - type: string | |
| format: uri-reference | |
| - type: 'null' | |
| prev: | |
| description: The previous page of data | |
| oneOf: | |
| - type: string | |
| format: uri-reference | |
| - type: 'null' | |
| next: | |
| description: The next page of data | |
| oneOf: | |
| - type: string | |
| format: uri-reference | |
| - type: 'null' |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment