Documentation
Documentation
http://example.com/documentation
Authentication
http://example.com/authentication
GettingStarted
http://example.com/getting-started
OpenAPI Specification
openapi: 3.1.0
info:
title: Persons API
description: |
This is a template APIs.json for a persons API, to be used in storytelling, training, and knowledge bases.
version: 0.1.0
contact:
name: API Evangelist
url: https://apievangelist.com
email: [email protected]
termsOfService: http://example.com/terms/
license:
name: Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International
identifier: CC-BY-NC-SA-4.0
url: https://creativecommons.org/licenses/by-nc-sa/4.0/deed.en
externalDocs:
description: Persons API Landing Page
url: http://example.com/persons
servers:
- url: https://api.example.com
description: Personion
tags:
- name: Persons
description: |
Placing and managing of persons placed for persons.
paths:
/persons:
get:
operationId: getPersons
summary: Retrieves Persons
description: Returns a list of all persons for the authenticated user.
security:
- apiKeys: []
tags:
- Persons
responses:
'200':
description: A list of persons
headers:
RateLimit:
$ref: '#/components/headers/RateLimit'
content:
application/json:
schema:
$ref: '#/components/schemas/WrapperResponseCollection'
examples:
PersonCollection:
$ref: '#/components/examples/PersonCollection'
application/xml:
schema:
$ref: '#/components/schemas/WrapperResponseCollection'
examples:
PersonCollection:
$ref: '#/components/examples/PersonCollection'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
post:
operationId: createPerson
summary: Persons Create Person
description: Creating a new person for sending to a recipient.
tags:
- Persons
security:
- apiKeys: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Person'
examples:
Person:
$ref: '#/components/examples/Person'
application/xml:
schema:
$ref: '#/components/schemas/Person'
examples:
Person:
$ref: '#/components/examples/Person'
responses:
'201':
description: Person Successful
content:
application/json:
schema:
$ref: '#/components/schemas/WrapperResponseObject'
examples:
SinglePerson:
$ref: '#/components/examples/SinglePerson'
application/xml:
schema:
$ref: '#/components/schemas/WrapperResponseObject'
examples:
SinglePerson:
$ref: '#/components/examples/SinglePerson'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
/persons/{personId}:
parameters:
- $ref: '#/components/parameters/PersonId'
get:
summary: Persons Retrieve Person
description: Returns the details of a specific person.
operationId: getPerson
tags:
- Persons
security:
- apiKeys: []
responses:
'200':
description: Person Details
headers:
RateLimit:
$ref: '#/components/headers/RateLimit'
content:
application/json:
schema:
$ref: '#/components/schemas/WrapperResponseObject'
examples:
SinglePerson:
$ref: '#/components/examples/SinglePerson'
application/xml:
schema:
$ref: '#/components/schemas/WrapperResponseObject'
examples:
SinglePerson:
$ref: '#/components/examples/SinglePerson'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
put:
summary: Persons Update Person
description: Updates a single person.
operationId: updatePerson
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Person'
examples:
Person:
$ref: '#/components/examples/Person'
application/xml:
schema:
$ref: '#/components/schemas/Person'
examples:
Person:
$ref: '#/components/examples/Person'
security:
- apiKeys: []
tags:
- Persons
responses:
'204':
description: Person Updated
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
delete:
summary: Persons Delete Person
description: Deletes a person.
operationId: deletePerson
security:
- apiKeys: []
tags:
- Persons
responses:
'204':
description: Person Deleted
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
/persons/{personId}/cancle:
parameters:
- $ref: '#/components/parameters/PersonId'
put:
summary: Persons Cancel Person
description: Cancels a single person.
operationId: sendPerson
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Person'
examples:
Person:
$ref: '#/components/examples/Person'
application/xml:
schema:
$ref: '#/components/schemas/Person'
examples:
Person:
$ref: '#/components/examples/Person'
security:
- apiKeys: []
tags:
- Persons
responses:
'204':
description: Person Sent
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
components:
examples:
PersonCollection:
value:
meta:
page: 1
pageSize: 10
totalPages: 2
data:
- id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
name: Kin Lane
description: My name is Kin Lane. I am a writer, storyteller, and forever recovering technologist. If you’ve heard of my name before, you probably know me as the API Evangelist, covering the technology, business, people, and policies of APIs.
email: [email protected]
links:
self: https://api.example.com/persons
next: https://api.example.com/persons?page=2
SinglePerson:
value:
meta:
page: 1
pageSize: 10
totalPages: 2
data:
id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
name: Kin Lane
description: My name is Kin Lane. I am a writer, storyteller, and forever recovering technologist. If you’ve heard of my name before, you probably know me as the API Evangelist, covering the technology, business, people, and policies of APIs.
email: [email protected]
links:
self: https://api.example.com/persons
Person:
value:
name: Kin Lane
description: My name is Kin Lane. I am a writer, storyteller, and forever recovering technologist. If you’ve heard of my name before, you probably know me as the API Evangelist, covering the technology, business, people, and policies of APIs.
email: [email protected]
securitySchemes:
apiKeys:
type: apiKey
name: api-key
in: header
parameters:
PersonId:
name: personId
in: path
required: true
description: The ID of the person to retrieve.
schema:
type: string
format: uuid
minLength: 36
maxLength: 36
pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
example: 1725ff48-ab45-4bb5-9d02-88745177dedb
schemas:
WrapperResponseCollection:
description: This is a generic request/response wrapper which contains both data and links which serve as hypermedia controls (HATEOAS).
type: object
required:
- meta
- data
- links
properties:
meta:
$ref: '#/components/schemas/Meta'
data:
description: The wrapper for a collection is an array of objects.
type: array
maxItems: 100
minItems: 1
items:
$ref: '#/components/schemas/Person'
links:
$ref: '#/components/schemas/LinksPagination'
xml:
name: data
WrapperResponseObject:
description: This is a generic request/response wrapper which contains both data and links which serve as hypermedia controls (HATEOAS).
type: object
required:
- meta
- data
- links
properties:
meta:
$ref: '#/components/schemas/Meta'
data:
$ref: '#/components/schemas/Person'
links:
$ref: '#/components/schemas/LinksSelf'
xml:
name: data
LinksSelf:
type: object
description: A link to reference each person.
required:
- self
properties:
self:
type: string
description: A URL to person returned.
format: uri
minLength: 10
maxLength: 2048
Meta:
type: object
description: The metadata for each response.
required:
- page
- totalPages
properties:
page:
type: integer
description: The page represented in response.
minLength: 1
maxLength: 1000
pageSize:
type: integer
minLength: 1
maxLength: 1000
description: The overall page size limits.
totalPages:
type: integer
description: The total number of pages.
minLength: 1
maxLength: 1000
LinksPagination:
type: object
description: The handling of each page.
properties:
next:
type: string
description: The next page in results.
format: uri
minLength: 10
maxLength: 2048
prev:
type: string
description: The previous page in results.
format: uri
minLength: 10
maxLength: 2048
Person:
type: object
description: A Schema.org compliant person object.
xml:
name: person
required:
- identifier
- name
properties:
identifier:
type: string
format: uuid
description: Unique identifier for the person.
minLength: 36
maxLength: 36
pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
example: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
name:
type: integer
description: Name of the person.
minLength: 10
maxLength: 10
example: Kin Lane
descripton:
type: string
description: The description of the person.
minLength: 10
maxLength: 2500
example: The peson behind API Evangelist.
email:
type: string
description: An email for the person.
minLength: 10
maxLength: 2048
example: '[email protected]'
Problem:
type: object
description: This is a Problem Details for HTTP APIs object.
required:
- title
- status
xml:
name: problem
namespace: urn:ietf:rfc:7807
properties:
type:
type: string
description: A URI reference that identifies the problem type
example: https://example.com/probs/out-of-credit
minLength: 10
maxLength: 2048
title:
type: string
description: A short, human-readable summary of the problem type
example: You do not have enough credit.
minLength: 10
maxLength: 250
detail:
type: string
description: A human-readable explanation specific to this occurrence of the problem
example: Your current balance is 30, but that costs 50.
minLength: 10
maxLength: 1000
instance:
type: string
description: A URI reference that identifies the specific occurrence of the problem
example: /account/12345/msgs/abc
minLength: 10
maxLength: 250
status:
type: integer
description: The HTTP status code
example: 400
minLength: 3
maxLength: 3
headers:
RateLimit:
description: |
The RateLimit header communicates quota policies. It contains a `limit` to
convey the expiring limit, `remaining` to convey the remaining quota units,
and `reset` to convey the time window reset time.
schema:
type: string
minLength: 10
maxLength: 250
example: limit=10, remaining=0, reset=10
Retry-After:
description: |
The Retry-After header indicates how long the user agent should wait before making a follow-up request.
The value is in seconds and can be an integer or a date in the future.
If the value is an integer, it indicates the number of seconds to wait.
If the value is a date, it indicates the time at which the user agent should make a follow-up request.
schema:
type: string
minLength: 10
maxLength: 250
examples:
integer:
value: '120'
summary: Retry after 120 seconds
date:
value: 'Fri, 31 Dec 2021 23:59:59 GMT'
summary: Retry after the specified date
responses:
BadRequest:
description: Bad Request
headers:
RateLimit:
$ref: '#/components/headers/RateLimit'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://example.com/errors/bad-request
title: Bad Request
status: 400
detail: The request is invalid or missing required parameters.
application/problem+xml:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://example.com/errors/bad-request
title: Bad Request
status: 400
detail: The request is invalid or missing required parameters.
Conflict:
description: Conflict
headers:
RateLimit:
$ref: '#/components/headers/RateLimit'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://example.com/errors/conflict
title: Conflict
status: 409
detail: There is a conflict with an existing resource.
application/problem+xml:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://example.com/errors/conflict
title: Conflict
status: 409
detail: There is a conflict with an existing resource.
Forbidden:
description: Forbidden
headers:
RateLimit:
$ref: '#/components/headers/RateLimit'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://example.com/errors/forbidden
title: Forbidden
status: 403
detail: Access is forbidden with the provided credentials.
application/problem+xml:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://example.com/errors/forbidden
title: Forbidden
status: 403
detail: Access is forbidden with the provided credentials.
InternalServerError:
description: Internal Server Error
headers:
RateLimit:
$ref: '#/components/headers/RateLimit'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://example.com/errors/internal-server-error
title: Internal Server Error
status: 500
detail: An unexpected error occurred.
application/problem+xml:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://example.com/errors/internal-server-error
title: Internal Server Error
status: 500
detail: An unexpected error occurred.
NotFound:
description: Not Found
headers:
RateLimit:
$ref: '#/components/headers/RateLimit'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://example.com/errors/not-found
title: Not Found
status: 404
detail: The requested resource was not found.
application/problem+xml:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://example.com/errors/not-found
title: Not Found
status: 404
detail: The requested resource was not found.
TooManyRequests:
description: Too Many Requests
headers:
RateLimit:
$ref: '#/components/headers/RateLimit'
Retry-After:
$ref: '#/components/headers/Retry-After'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://example.com/errors/too-many-requests
title: Too Many Requests
status: 429
detail: You have exceeded the rate limit.
application/problem+xml:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://example.com/errors/too-many-requests
title: Too Many Requests
status: 429
detail: You have exceeded the rate limit.
Unauthorized:
description: Unauthorized
headers:
RateLimit:
$ref: '#/components/headers/RateLimit'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://example.com/errors/unauthorized
title: Unauthorized
status: 401
detail: You do not have the necessary permissions.
application/problem+xml:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://example.com/errors/unauthorized
title: Unauthorized
status: 401
detail: You do not have the necessary permissions.