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: Organizations API
description: |
This is a template APIs.json for a organizations 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: Organizations API Landing Page
url: http://example.com/organizations
servers:
- url: https://api.example.com
description: Production
tags:
- name: Organizations
description: |
Placing and managing of organizations placed for products.
paths:
/organizations:
get:
operationId: getOrganizations
summary: Retrieves Organizations
description: Returns a list of all organizations for the authenticated user.
security:
- apiKeys: []
tags:
- Organizations
responses:
'200':
description: A list of organizations
headers:
RateLimit:
$ref: '#/components/headers/RateLimit'
content:
application/json:
schema:
$ref: '#/components/schemas/WrapperResponseCollection'
examples:
OrganizationCollection:
$ref: '#/components/examples/OrganizationCollection'
application/xml:
schema:
$ref: '#/components/schemas/WrapperResponseCollection'
examples:
OrganizationCollection:
$ref: '#/components/examples/OrganizationCollection'
'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: createOrganization
summary: Organizations Create Organization
description: Creating a new organization for sending to a recipient.
tags:
- Organizations
security:
- apiKeys: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Organization'
examples:
Organization:
$ref: '#/components/examples/Organization'
application/xml:
schema:
$ref: '#/components/schemas/Organization'
examples:
Organization:
$ref: '#/components/examples/Organization'
responses:
'201':
description: Organization Successful
content:
application/json:
schema:
$ref: '#/components/schemas/WrapperResponseObject'
examples:
SingleOrganization:
$ref: '#/components/examples/SingleOrganization'
application/xml:
schema:
$ref: '#/components/schemas/WrapperResponseObject'
examples:
SingleOrganization:
$ref: '#/components/examples/SingleOrganization'
'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'
/organizations/{organizationId}:
parameters:
- $ref: '#/components/parameters/OrganizationId'
get:
summary: Organizations Retrieve Organization
description: Returns the details of a specific organization.
operationId: getOrganization
tags:
- Organizations
security:
- apiKeys: []
responses:
'200':
description: Organization Details
headers:
RateLimit:
$ref: '#/components/headers/RateLimit'
content:
application/json:
schema:
$ref: '#/components/schemas/WrapperResponseObject'
examples:
SingleOrganization:
$ref: '#/components/examples/SingleOrganization'
application/xml:
schema:
$ref: '#/components/schemas/WrapperResponseObject'
examples:
SingleOrganization:
$ref: '#/components/examples/SingleOrganization'
'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: Organizations Update Organization
description: Updates a single organization.
operationId: updateOrganization
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Organization'
examples:
Organization:
$ref: '#/components/examples/Organization'
application/xml:
schema:
$ref: '#/components/schemas/Organization'
examples:
Organization:
$ref: '#/components/examples/Organization'
security:
- apiKeys: []
tags:
- Organizations
responses:
'204':
description: Organization 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: Organizations Delete Organization
description: Deletes a organization.
operationId: deleteOrganization
security:
- apiKeys: []
tags:
- Organizations
responses:
'204':
description: Organization 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'
/organizations/{organizationId}/cancle:
parameters:
- $ref: '#/components/parameters/OrganizationId'
put:
summary: Organizations Cancel Organization
description: Cancels a single organization.
operationId: sendOrganization
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Organization'
examples:
Organization:
$ref: '#/components/examples/Organization'
application/xml:
schema:
$ref: '#/components/schemas/Organization'
examples:
Organization:
$ref: '#/components/examples/Organization'
security:
- apiKeys: []
tags:
- Organizations
responses:
'204':
description: Organization 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:
OrganizationCollection:
value:
meta:
page: 1
pageSize: 10
totalPages: 2
data:
- id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
name: API Evangelist LLC
description: API Evangelist is the working toolbox of Kin Lane, designed to explore and make sense of the technology, business, policies, and people involved in creating and consuming HTTP APIs. The site serves as an evolving repository of information that covers nearly every aspect of API operations. It helps enterprises, startups, analysts, consultants, and other stakeholders assess, manage, and govern the expansive API landscape that powers various business sectors.
email: [email protected]
links:
self: https://api.example.com/organizations
next: https://api.example.com/organizations?page=2
SingleOrganization:
value:
meta:
page: 1
pageSize: 10
totalPages: 2
data:
id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
name: API Evangelist LLC
description: API Evangelist is the working toolbox of Kin Lane, designed to explore and make sense of the technology, business, policies, and people involved in creating and consuming HTTP APIs. The site serves as an evolving repository of information that covers nearly every aspect of API operations. It helps enterprises, startups, analysts, consultants, and other stakeholders assess, manage, and govern the expansive API landscape that powers various business sectors.
email: [email protected]
links:
self: https://api.example.com/organizations
Organization:
value:
name: API Evangelist LLC
description: API Evangelist is the working toolbox of Kin Lane, designed to explore and make sense of the technology, business, policies, and people involved in creating and consuming HTTP APIs. The site serves as an evolving repository of information that covers nearly every aspect of API operations. It helps enterprises, startups, analysts, consultants, and other stakeholders assess, manage, and govern the expansive API landscape that powers various business sectors.
email: [email protected]
securitySchemes:
apiKeys:
type: apiKey
name: api-key
in: header
parameters:
OrganizationId:
name: organizationId
in: path
required: true
description: The ID of the organization 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/Organization'
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/Organization'
links:
$ref: '#/components/schemas/LinksSelf'
xml:
name: data
LinksSelf:
type: object
description: A link to reference each organization.
required:
- self
properties:
self:
type: string
description: A URL to organization 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
Organization:
type: object
description: A Schema.org compliant organization object.
xml:
name: organization
required:
- identifier
- name
properties:
identifier:
type: string
format: uuid
description: Unique identifier for the organization.
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 organization.
minLength: 10
maxLength: 10
example: API Evangelist LLC
descripton:
type: string
description: The description of the organization.
minLength: 10
maxLength: 2500
example: API Evangelist is the working toolbox of Kin Lane, designed to explore and make sense of the technology, business, policies, and people involved in creating and consuming HTTP APIs. The site serves as an evolving repository of information that covers nearly every aspect of API operations. It helps enterprises, startups, analysts, consultants, and other stakeholders assess, manage, and govern the expansive API landscape that powers various business sectors.
email:
type: string
description: An email for the organization.
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.