808 lines
27 KiB
YAML
808 lines
27 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
version: "1.0.0"
|
|
title: 'IPFS Pinning Service API'
|
|
x-logo:
|
|
url: "https://bafybeidehxarrk54mkgyl5yxbgjzqilp6tkaz2or36jhq24n3rdtuven54.ipfs.dweb.link/?filename=ipfs-pinning-service.svg"
|
|
contact:
|
|
name: IPFS
|
|
url: https://github.com/ipfs/pinning-services-api-spec
|
|
description: "
|
|
|
|
|
|
## About this spec
|
|
|
|
The IPFS Pinning Service API is intended to be an implementation-agnostic API:
|
|
|
|
- For use and implementation by pinning service providers
|
|
|
|
- For use in client mode by IPFS nodes and GUI-based applications
|
|
|
|
|
|
### Document scope and intended audience
|
|
|
|
The intended audience of this document is **IPFS developers** building pinning service clients or servers compatible with this OpenAPI spec.
|
|
Your input and feedback are welcome and valuable as we develop this API spec. Please join the design discussion at [github.com/ipfs/pinning-services-api-spec](https://github.com/ipfs/pinning-services-api-spec).
|
|
|
|
|
|
**IPFS users** should see the tutorial at [docs.ipfs.io/how-to/work-with-pinning-services](https://docs.ipfs.io/how-to/work-with-pinning-services/) instead.
|
|
|
|
|
|
### Related resources
|
|
|
|
The latest version of this spec and additional resources can be found at:
|
|
|
|
- Specification: https://github.com/ipfs/pinning-services-api-spec/raw/main/ipfs-pinning-service.yaml
|
|
|
|
- Docs: https://ipfs.github.io/pinning-services-api-spec/
|
|
|
|
- Clients and services: https://github.com/ipfs/pinning-services-api-spec#adoption
|
|
|
|
|
|
# Schemas
|
|
|
|
This section describes the most important object types and conventions.
|
|
|
|
|
|
A full list of fields and schemas can be found in the `schemas` section of the [YAML file](https://github.com/ipfs/pinning-services-api-spec/blob/master/ipfs-pinning-service.yaml).
|
|
|
|
|
|
## Identifiers
|
|
|
|
### cid
|
|
|
|
[Content Identifier (CID)](https://docs.ipfs.io/concepts/content-addressing/) points at the root of a DAG that is pinned recursively.
|
|
|
|
### requestid
|
|
|
|
Unique identifier of a pin request.
|
|
|
|
|
|
When a pin is created, the service responds with unique `requestid` that can be later used for pin removal. When the same `cid` is pinned again, a different `requestid` is returned to differentiate between those pin requests.
|
|
|
|
|
|
Service implementation should use UUID, `hash(accessToken,Pin,PinStatus.created)`, or any other opaque identifier that provides equally strong protection against race conditions.
|
|
|
|
|
|
## Objects
|
|
|
|
### Pin object
|
|
|
|
|
|
|
|
|
|
|
|
The `Pin` object is a representation of a pin request.
|
|
|
|
|
|
It includes the `cid` of data to be pinned, as well as optional metadata in `name`, `origins`, and `meta`.
|
|
Addresses provided in `origins` list are relevant only during the initial pinning, and don't need to be persisted by the pinning service.
|
|
|
|
|
|
### Pin status response
|
|
|
|
|
|
|
|
|
|
|
|
The `PinStatus` object is a representation of the current state of a pinning operation.
|
|
|
|
It includes values from the original `Pin` object, along with the current `status` and globally unique `requestid` of the entire pinning request, which can be used for future status checks and management.
|
|
Addresses in the `delegates` array are peers designated by pinning service that will receive the pin data over bitswap (more details in the [Provider hints](#section/Provider-hints) section). Any additional vendor-specific information is returned in optional `info`.
|
|
|
|
|
|
# The pin lifecycle
|
|
|
|
|
|
|
|
|
|
|
|
## Creating a new pin object
|
|
|
|
The user sends a `Pin` object to `POST /pins` and receives a `PinStatus` response:
|
|
|
|
- `requestid` in `PinStatus` is the identifier of the pin operation, which can can be used for checking status, and removing the pin in the future
|
|
|
|
- `status` in `PinStatus` indicates the current state of a pin
|
|
|
|
|
|
## Checking status of in-progress pinning
|
|
|
|
`status` (in `PinStatus`) may indicate one of the two pending states: `queued` or `pinning`:
|
|
|
|
- `queued` is passive: the pin was added to the queue but the service isn't consuming any resources to retrieve it yet.
|
|
- `pinning` is active: the pinning service is trying to retrieve the CIDs by finding providers for all involved CIDs, connect to these providers and download data from them.
|
|
|
|
When a new pin object is created it typically starts in a `queued` state. Once the pinning service actively seeks to retrieve the file it changes to `pinning`. `pinning` typically means that the data behind `Pin.cid` was not found on the pinning service and is being fetched from the IPFS network at large, which may take time.
|
|
|
|
In either case, the user can periodically check pinning progress via `GET /pins/{requestid}` until pinning is successful, or the user decides to remove the pending pin.
|
|
|
|
## Replacing an existing pin object
|
|
|
|
The user can replace an existing pin object via `POST /pins/{requestid}`. This is a shortcut for removing a pin object identified by `requestid` and creating a new one in a single API call that protects against undesired garbage collection of blocks common to both pins. Useful when updating a pin representing a huge dataset where most of blocks did not change. The new pin object `requestid` is returned in the `PinStatus` response. The old pin object is deleted automatically.
|
|
|
|
|
|
## Removing a pin object
|
|
|
|
A pin object can be removed via `DELETE /pins/{requestid}`.
|
|
|
|
|
|
|
|
# Provider hints
|
|
|
|
Provider hints take the form of two [multiaddr](https://docs.ipfs.io/concepts/glossary/#multiaddr) lists: `Pin.origins` and `PinStatus.delegates`
|
|
|
|
|
|
## Pin.origins
|
|
|
|
A list of known sources (providers) of the data. Sent by a client in a pin request.
|
|
Pinning service will try to connect to them to speed up data transfer.
|
|
|
|
|
|
## PinStatus.delegates
|
|
|
|
A list of temporary destination (retrievers) for the data. Returned by pinning service in a response for a pin request.
|
|
These peers are provided by a pinning service for the purpose of fetching data about to be pinned.
|
|
|
|
|
|
## Optimizing for speed and connectivity
|
|
|
|
Both ends should attempt to preconnect to each other:
|
|
|
|
- Delegates should always preconnect to origins
|
|
|
|
- Clients who initiate pin request and also have the pinned data in their own local datastore should preconnect to delegates
|
|
|
|
|
|
**NOTE:** Connections to multiaddrs in `origins` and `delegates` arrays should
|
|
be attempted in best-effort fashion, and dial failure should not fail the
|
|
pinning operation. When unable to act on explicit provider hints, DHT and
|
|
other discovery methods should be used as a fallback by a pinning service.
|
|
|
|
|
|
## Rationale
|
|
|
|
A pinning service will use the DHT and other discovery methods to locate pinned
|
|
content; however, it may not be able to retrieve data if the only provider
|
|
has no publicly diallable address (e.g. a desktop peer behind a restrictive NAT/firewall).
|
|
|
|
|
|
Leveraging provider hints mitigates potential connectivity issues and speeds up the content routing phase.
|
|
If a client has the data in their own datastore or already knows of other providers, the transfer will start immediately.
|
|
|
|
|
|
The most common scenario is a client putting its own IPFS node's multiaddrs in
|
|
`Pin.origins`, and then attempt to connect to every multiaddr returned by a
|
|
pinning service in `PinStatus.delegates` to initiate transfer. At the same
|
|
time, a pinning service will try to connect to multiaddrs provided by the client
|
|
in `Pin.origins`.
|
|
|
|
|
|
This ensures data transfer starts immediately (without waiting for provider
|
|
discovery over DHT), and mutual direct dial between a client and a service
|
|
works around peer routing issues in restrictive network topologies, such as
|
|
NATs, firewalls, etc.
|
|
|
|
|
|
**NOTE:** All multiaddrs MUST end with `/p2p/{peerID}` and SHOULD be fully
|
|
resolved and confirmed to be dialable from the public internet. Avoid sending
|
|
addresses from local networks.
|
|
|
|
|
|
# Custom metadata
|
|
|
|
Pinning services are encouraged to add support for additional features by leveraging the optional `Pin.meta` and `PinStatus.info` fields.
|
|
While these attributes can be application- or vendor-specific, we encourage the community at large to leverage these attributes as a sandbox to come up with conventions that could become part of future revisions of this API.
|
|
|
|
## Pin metadata
|
|
|
|
String keys and values passed in `Pin.meta` are persisted with the pin object.
|
|
This is an opt-in feature: It is OK for a client to omit or ignore these optional attributes, and doing so should not impact the basic pinning functionality.
|
|
|
|
|
|
Potential uses:
|
|
|
|
- `Pin.meta[app_id]`: Attaching a unique identifier to pins created by an app enables meta-filtering pins per app
|
|
|
|
- `Pin.meta[vendor_policy]`: Vendor-specific policy (for example: which region to use, how many copies to keep)
|
|
|
|
|
|
### Filtering based on metadata
|
|
|
|
The contents of `Pin.meta` can be used as an advanced search filter for situations where searching by `name` and `cid` is not enough.
|
|
|
|
|
|
Metadata key matching rule is `AND`:
|
|
|
|
- lookup returns pins that have `meta` with all key-value pairs matching the passed values
|
|
|
|
- pin metadata may have more keys, but only ones passed in the query are used for filtering
|
|
|
|
|
|
The wire format for the `meta` when used as a query parameter is a [URL-escaped](https://en.wikipedia.org/wiki/Percent-encoding) stringified JSON object.
|
|
A lookup example for pins that have a `meta` key-value pair `{\"app_id\":\"UUID\"}` is:
|
|
|
|
- `GET /pins?meta=%7B%22app_id%22%3A%22UUID%22%7D`
|
|
|
|
|
|
|
|
## Pin status info
|
|
|
|
Additional `PinStatus.info` can be returned by pinning service.
|
|
|
|
|
|
Potential uses:
|
|
|
|
- `PinStatus.info[status_details]`: more info about the current status (queue
|
|
position, percentage of transferred data, summary of where data is stored, etc); when
|
|
`PinStatus.status=failed`, it could provide a reason why a pin operation
|
|
failed (e.g. lack of funds, DAG too big, etc.)
|
|
|
|
- `PinStatus.info[dag_size]`: the size of pinned data, along with DAG overhead
|
|
|
|
- `PinStatus.info[raw_size]`: the size of data without DAG overhead (eg. unixfs)
|
|
|
|
- `PinStatus.info[pinned_until]`: if vendor supports time-bound pins, this could indicate when the pin will expire
|
|
|
|
|
|
# Pagination and filtering
|
|
|
|
Pin objects can be listed by executing `GET /pins` with optional parameters:
|
|
|
|
|
|
- When no filters are provided, the endpoint will return a small batch of the 10 most
|
|
recently created items, from the latest to the oldest.
|
|
|
|
- The number of returned items can be adjusted with the `limit` parameter
|
|
(implicit default is 10).
|
|
|
|
- If the value in `PinResults.count` is bigger than the length of
|
|
`PinResults.results`, the client can infer there are more results that can be queried.
|
|
|
|
- To read more items, pass the `before` filter with the timestamp from
|
|
`PinStatus.created` found in the oldest item in the current batch of results.
|
|
Repeat to read all results.
|
|
|
|
- Returned results can be fine-tuned by applying optional `after`, `cid`, `name`,
|
|
`status`, or `meta` filters.
|
|
|
|
|
|
> **Note**: pagination by the `created` timestamp requires each value to be
|
|
globally unique. Any future considerations to add support for bulk creation
|
|
must account for this.
|
|
|
|
|
|
"
|
|
|
|
servers:
|
|
- url: "/api/"
|
|
|
|
tags:
|
|
- name: pins
|
|
|
|
paths:
|
|
/pins:
|
|
get:
|
|
x-mojo-to: "Pins#list"
|
|
operationId: getPins
|
|
summary: List pin objects
|
|
description: List all the pin objects, matching optional filters; when no filter is provided, only successful pins are returned
|
|
tags:
|
|
- pins
|
|
parameters:
|
|
- $ref: '#/components/parameters/cid'
|
|
- $ref: '#/components/parameters/name'
|
|
- $ref: '#/components/parameters/match'
|
|
- $ref: '#/components/parameters/status'
|
|
- $ref: '#/components/parameters/before'
|
|
- $ref: '#/components/parameters/after'
|
|
- $ref: '#/components/parameters/limit'
|
|
- $ref: '#/components/parameters/meta'
|
|
responses:
|
|
'200':
|
|
description: Successful response (PinResults object)
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PinResults'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'409':
|
|
$ref: '#/components/responses/InsufficientFunds'
|
|
'4XX':
|
|
$ref: '#/components/responses/CustomServiceError'
|
|
'5XX':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
post:
|
|
x-mojo-to: "Pins#add"
|
|
operationId: addPin
|
|
summary: Add pin object
|
|
description: Add a new pin object for the current access token
|
|
tags:
|
|
- pins
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Pin'
|
|
responses:
|
|
'202':
|
|
description: Successful response (PinStatus object)
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PinStatus'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'409':
|
|
$ref: '#/components/responses/InsufficientFunds'
|
|
'4XX':
|
|
$ref: '#/components/responses/CustomServiceError'
|
|
'5XX':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
|
|
/pins/{requestid}:
|
|
parameters:
|
|
- name: requestid
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
get:
|
|
x-mojo-to: "Pins#get"
|
|
operationId: getPinByRequestId
|
|
summary: Get pin object
|
|
description: Get a pin object and its status
|
|
tags:
|
|
- pins
|
|
responses:
|
|
'200':
|
|
description: Successful response (PinStatus object)
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PinStatus'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'409':
|
|
$ref: '#/components/responses/InsufficientFunds'
|
|
'4XX':
|
|
$ref: '#/components/responses/CustomServiceError'
|
|
'5XX':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
post:
|
|
x-mojo-to: "Pins#replace"
|
|
operationId: replacePinByRequestId
|
|
summary: Replace pin object
|
|
description: Replace an existing pin object (shortcut for executing remove and add operations in one step to avoid unnecessary garbage collection of blocks present in both recursive pins)
|
|
tags:
|
|
- pins
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Pin'
|
|
responses:
|
|
'202':
|
|
description: Successful response (PinStatus object)
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PinStatus'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'409':
|
|
$ref: '#/components/responses/InsufficientFunds'
|
|
'4XX':
|
|
$ref: '#/components/responses/CustomServiceError'
|
|
'5XX':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
delete:
|
|
x-mojo-to: "Pins#delete"
|
|
operationId: deletePinByRequestId
|
|
summary: Remove pin object
|
|
description: Remove a pin object
|
|
tags:
|
|
- pins
|
|
responses:
|
|
'202':
|
|
description: Successful response (no body, pin removed)
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'409':
|
|
$ref: '#/components/responses/InsufficientFunds'
|
|
'4XX':
|
|
$ref: '#/components/responses/CustomServiceError'
|
|
'5XX':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
|
|
components:
|
|
schemas:
|
|
|
|
PinResults:
|
|
description: Response used for listing pin objects matching request
|
|
type: object
|
|
required:
|
|
- count
|
|
- results
|
|
properties:
|
|
count:
|
|
description: The total number of pin objects that exist for passed query filters
|
|
type: integer
|
|
format: int32
|
|
minimum: 0
|
|
example: 1
|
|
results:
|
|
description: An array of PinStatus results
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/PinStatus'
|
|
uniqueItems: true
|
|
minItems: 0
|
|
maxItems: 1000
|
|
|
|
PinStatus:
|
|
description: Pin object with status
|
|
type: object
|
|
required:
|
|
- requestid
|
|
- status
|
|
- created
|
|
- pin
|
|
- delegates
|
|
properties:
|
|
requestid:
|
|
description: Globally unique identifier of the pin request; can be used to check the status of ongoing pinning, or pin removal
|
|
type: string
|
|
format: uuid
|
|
example: "UniqueIdOfPinRequest"
|
|
status:
|
|
$ref: '#/components/schemas/Status'
|
|
created:
|
|
description: Immutable timestamp indicating when a pin request entered a pinning service; can be used for filtering results and pagination
|
|
type: string
|
|
format: date-time # RFC 3339, section 5.6
|
|
example: "2020-07-27T17:32:28.276Z"
|
|
pin:
|
|
$ref: '#/components/schemas/Pin'
|
|
delegates:
|
|
$ref: '#/components/schemas/Delegates'
|
|
info:
|
|
$ref: '#/components/schemas/StatusInfo'
|
|
|
|
Pin:
|
|
description: Pin object
|
|
type: object
|
|
required:
|
|
- cid
|
|
properties:
|
|
cid:
|
|
description: Content Identifier (CID) to be pinned recursively
|
|
type: string
|
|
example: "QmCIDToBePinned"
|
|
name:
|
|
description: Optional name for pinned data; can be used for lookups later
|
|
type: string
|
|
maxLength: 255
|
|
example: "PreciousData.pdf"
|
|
origins:
|
|
$ref: '#/components/schemas/Origins'
|
|
meta:
|
|
$ref: '#/components/schemas/PinMeta'
|
|
|
|
Status:
|
|
description: Status a pin object can have at a pinning service
|
|
type: string
|
|
enum:
|
|
- queued # pinning operation is waiting in the queue; additional info can be returned in info[status_details]
|
|
- pinning # pinning in progress; additional info can be returned in info[status_details]
|
|
- pinned # pinned successfully
|
|
- failed # pinning service was unable to finish pinning operation; additional info can be found in info[status_details]
|
|
|
|
Delegates:
|
|
description: List of multiaddrs designated by pinning service that will receive the pin data; see Provider Hints in the docs
|
|
type: array
|
|
items:
|
|
type: string
|
|
uniqueItems: true
|
|
minItems: 1
|
|
maxItems: 20
|
|
example: ['/ip4/203.0.113.1/tcp/4001/p2p/QmServicePeerId']
|
|
|
|
Origins:
|
|
description: Optional list of multiaddrs known to provide the data; see Provider Hints in the docs
|
|
type: array
|
|
items:
|
|
type: string
|
|
uniqueItems: true
|
|
minItems: 0
|
|
maxItems: 20
|
|
example: ['/ip4/203.0.113.142/tcp/4001/p2p/QmSourcePeerId', '/ip4/203.0.113.114/udp/4001/quic/p2p/QmSourcePeerId']
|
|
|
|
PinMeta:
|
|
description: Optional metadata for pin object
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
minProperties: 0
|
|
maxProperties: 1000
|
|
example:
|
|
app_id: "99986338-1113-4706-8302-4420da6158aa" # Pin.meta[app_id], useful for filtering pins per app
|
|
|
|
StatusInfo:
|
|
description: Optional info for PinStatus response
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
minProperties: 0
|
|
maxProperties: 1000
|
|
example:
|
|
status_details: "Queue position: 7 of 9" # PinStatus.info[status_details], when status=queued
|
|
|
|
TextMatchingStrategy:
|
|
description: Alternative text matching strategy
|
|
type: string
|
|
default: exact
|
|
enum:
|
|
- exact # full match, case-sensitive (the implicit default)
|
|
- iexact # full match, case-insensitive
|
|
- partial # partial match, case-sensitive
|
|
- ipartial # partial match, case-insensitive
|
|
|
|
Failure:
|
|
description: Response for a failed request
|
|
type: object
|
|
required:
|
|
- error
|
|
properties:
|
|
error:
|
|
type: object
|
|
required:
|
|
- reason
|
|
properties:
|
|
reason:
|
|
type: string
|
|
description: Mandatory string identifying the type of error
|
|
example: "ERROR_CODE_FOR_MACHINES"
|
|
details:
|
|
type: string
|
|
description: Optional, longer description of the error; may include UUID of transaction for support, links to documentation etc
|
|
example: "Optional explanation for humans with more details"
|
|
|
|
parameters:
|
|
|
|
before:
|
|
description: Return results created (queued) before provided timestamp
|
|
name: before
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: string
|
|
format: date-time # RFC 3339, section 5.6
|
|
example: "2020-07-27T17:32:28.276Z"
|
|
|
|
after:
|
|
description: Return results created (queued) after provided timestamp
|
|
name: after
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: string
|
|
format: date-time # RFC 3339, section 5.6
|
|
example: "2020-07-27T17:32:28.276Z"
|
|
|
|
limit:
|
|
description: Max records to return
|
|
name: limit
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
format: int32
|
|
minimum: 1
|
|
maximum: 1000
|
|
default: 10
|
|
|
|
cid:
|
|
description: Return pin objects responsible for pinning the specified CID(s); be aware that using longer hash functions introduces further constraints on the number of CIDs that will fit under the limit of 2000 characters per URL in browser contexts
|
|
name: cid
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
uniqueItems: true
|
|
minItems: 1
|
|
maxItems: 10
|
|
style: form # ?cid=Qm1,Qm2,bafy3
|
|
explode: false
|
|
example: ["Qm1","Qm2","bafy3"]
|
|
|
|
name:
|
|
description: Return pin objects with specified name (by default a case-sensitive, exact match)
|
|
name: name
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: string
|
|
maxLength: 255
|
|
example: "PreciousData.pdf"
|
|
|
|
match:
|
|
description: Customize the text matching strategy applied when the name filter is present; exact (the default) is a case-sensitive exact match, partial matches anywhere in the name, iexact and ipartial are case-insensitive versions of the exact and partial strategies
|
|
name: match
|
|
in: query
|
|
required: false
|
|
schema:
|
|
$ref: '#/components/schemas/TextMatchingStrategy'
|
|
example: exact
|
|
|
|
status:
|
|
description: Return pin objects for pins with the specified status (when missing, service should default to pinned only)
|
|
name: status
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Status'
|
|
uniqueItems: true
|
|
minItems: 1
|
|
style: form # ?status=queued,pinning
|
|
explode: false
|
|
example: ["queued","pinning"]
|
|
|
|
meta:
|
|
description: Return pin objects that match specified metadata keys passed as a string representation of a JSON object; when implementing a client library, make sure the parameter is URL-encoded to ensure safe transport
|
|
name: meta
|
|
in: query
|
|
required: false
|
|
content:
|
|
application/json: # ?meta={"foo":"bar"}
|
|
schema:
|
|
$ref: '#/components/schemas/PinMeta'
|
|
|
|
responses:
|
|
|
|
BadRequest:
|
|
description: Error response (Bad request)
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Failure'
|
|
examples:
|
|
BadRequestExample:
|
|
$ref: '#/components/examples/BadRequestExample'
|
|
|
|
Unauthorized:
|
|
description: Error response (Unauthorized; access token is missing or invalid)
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Failure'
|
|
examples:
|
|
UnauthorizedExample:
|
|
$ref: '#/components/examples/UnauthorizedExample'
|
|
|
|
NotFound:
|
|
description: Error response (The specified resource was not found)
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Failure'
|
|
examples:
|
|
NotFoundExample:
|
|
$ref: '#/components/examples/NotFoundExample'
|
|
|
|
InsufficientFunds:
|
|
description: Error response (Insufficient funds)
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Failure'
|
|
examples:
|
|
InsufficientFundsExample:
|
|
$ref: '#/components/examples/InsufficientFundsExample'
|
|
|
|
CustomServiceError:
|
|
description: Error response (Custom service error)
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Failure'
|
|
examples:
|
|
CustomServiceErrorExample:
|
|
$ref: '#/components/examples/CustomServiceErrorExample'
|
|
|
|
InternalServerError:
|
|
description: Error response (Unexpected internal server error)
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Failure'
|
|
examples:
|
|
InternalServerErrorExample:
|
|
$ref: '#/components/examples/InternalServerErrorExample'
|
|
|
|
examples:
|
|
|
|
BadRequestExample:
|
|
value:
|
|
error:
|
|
reason: "BAD_REQUEST"
|
|
details: "Explanation for humans with more details"
|
|
summary: A sample response to a bad request; reason will differ
|
|
|
|
UnauthorizedExample:
|
|
value:
|
|
error:
|
|
reason: "UNAUTHORIZED"
|
|
details: "Access token is missing or invalid"
|
|
summary: Response to an unauthorized request
|
|
|
|
NotFoundExample:
|
|
value:
|
|
error:
|
|
reason: "NOT_FOUND"
|
|
details: "The specified resource was not found"
|
|
summary: Response to a request for a resource that does not exist
|
|
|
|
InsufficientFundsExample:
|
|
value:
|
|
error:
|
|
reason: "INSUFFICIENT_FUNDS"
|
|
details: "Unable to process request due to the lack of funds"
|
|
summary: Response when access token run out of funds
|
|
|
|
CustomServiceErrorExample:
|
|
value:
|
|
error:
|
|
reason: "CUSTOM_ERROR_CODE_FOR_MACHINES"
|
|
details: "Optional explanation for humans with more details"
|
|
summary: Response when a custom error occured
|
|
|
|
InternalServerErrorExample:
|
|
value:
|
|
error:
|
|
reason: "INTERNAL_SERVER_ERROR"
|
|
details: "Explanation for humans with more details"
|
|
summary: Response when unexpected error occured
|
|
|
|
securitySchemes:
|
|
accessToken:
|
|
description: "
|
|
An opaque token is required to be sent with each request in the HTTP header:
|
|
|
|
- `Authorization: Bearer <access-token>`
|
|
|
|
|
|
The `access-token` should be generated per device, and the user should have the ability to revoke each token separately.
|
|
"
|
|
type: http
|
|
scheme: bearer
|
|
security:
|
|
- accessToken: []
|