ipfs-pinning-service.yaml

openapi: 3.0.0
info:
  version: "0.0.2"
  title: '(WIP) IPFS Pinning Service API'
  description: "
  
  
# Goal

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


## This spec is a work in progress! 🏗️

**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).**


# The pin object lifecycle


## Creating a new pin object

The user creates a pin object via `POST /pins` and receives a `PinStatus` response:

- `id` in `PinStatus` is `cid-of-pin-object`, which can can be used for modifying and/or 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 a pending state. This means 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 this case, the user can periodically check pinning progress via `GET /pins/{cid-of-pin-object}` until pinning is successful, or the user decides to remove the pending pin.


## Modifying an existing pin object

The user can modify an existing pin object via `POST /pins/{cid-of-pin-object}`. The new pin object `id` 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/{cid-of-pin-object}`.



# Provider hints

Pinning of new data can be accelerated by providing a list of known data
sources in `Pin.providers` and connecting at least one of them to pinning
service nodes at `PinStatus.providers`.


The most common scenario is a client putting own IPFS node's multiaddrs in
`Pin.providers`  and then directly connecting to every multiaddr returned by
Pinning Service in `PinStatus.providers` to initiate transfer.


This ensures data transfer starts immediately (without waiting for provider
discovery over DHT) and direct dial from a client works around peer routing
issues in restrictive network topologies such as NAT.


# Custom metadata

Pinning services are encouraged to add support for additional features by leveraging the following optional `meta` attributes. Note that it is OK to ommit or ignore `meta` attributes; doing so should not impact the basic pinning functionality.

- `PinStatus.meta[progress]`: Progress (as percent value) of an ongoing pinning operation, if possible to tell

- `PinStatus.meta[fail_reason]`: A service-specific reason why a pin operation failed (e.g. lack of funds, DAG too big, etc.)

- `Pin.meta[replication]`: This attribute could define how many copies a pinning service should keep



While these attributes can be vendor-specific, we encourage the community at large to leverage these `meta` attributes as a sandbox to come up with conventions that could become part of future revisions of this API.



# Authorization

An opaque authorization token is required to be sent with each request. There are two ways of doing so:

1. Using an HTTP header: `Authorization: Bearer <auth>`

2. Using a query parameter: `&auth=<auth>`


The `auth` token should be generated per device, and user should have ability to revoke each token separately.

"

servers:
  - url: https://api.example.com

paths:
  /pins:
    get:
      summary: List pin objects
      description: List all the pin objects, matching optional filters. When no filter is provided, only successfull pins are returned.
      tags:
        - pins
      parameters:
        - $ref: '#/components/parameters/cid'
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/auth'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PinResults'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      summary: Add an array of pin objects
      description: Add an array of pin objects for the current user.
      tags:
        - pins
      parameters:
        - $ref: '#/components/parameters/auth'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Pin'
              uniqueItems: true
              minItems: 1
              maxItems: 1000
      responses:
        '202':
          description: Accepted
          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'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /pins/{cid-of-pin-object}:
    parameters:
      - name: cid-of-pin-object
        in: path
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/auth'
    get:
      summary: Get pin object
      description: Get a pin object and its status.
      tags:
        - pins
      parameters:
        - $ref: '#/components/parameters/auth'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PinStatus'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      summary: Modify pin object
      description: Modify an existing pin object.
      tags:
        - pins
      parameters:
        - $ref: '#/components/parameters/auth'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Pin'
      responses:
        '202':
          description: Accepted
          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'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      summary: Remove pin object
      description: Remove a pin object.
      tags:
        - pins
      parameters:
        - $ref: '#/components/parameters/auth'
      responses:
        '202':
          description: Accepted
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $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
        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:
        - id
        - status
        - pin
        - providers
      properties:
        id:
          description: CID of pin object; can be used to check status of ongoing pinning
          type: string
        status:
          $ref: '#/components/schemas/Status'
        pin:
          $ref: '#/components/schemas/Pin'
        providers:
          $ref: '#/components/schemas/ServiceProviders'
        meta:
          $ref: '#/components/schemas/Meta'

    Pin:
      description: pin object
      type: object
      required:
        - cid
      properties:
        cid:
          description: CID to be pinned recursively
          type: string
        providers:
          $ref: '#/components/schemas/DataProviders'
        meta:
          $ref: '#/components/schemas/Meta'

    Status:
      description: status a pin object can have at a pinning service
      type: string
      enum:
        - pinning    # pinning in progress, optional details can be returned in meta[pinning_status]
        - pinned     # pinned successfully
        - failed     # pining service was unable to finish pinning operation, optional details can be found in meta[fail_reason]
        - unpinned   # data is no longer pinned

    ServiceProviders:
      description: list of multiaddrs designated by pinning service for transferring any new data from external peers
      type: array
      items:
        type: string
      uniqueItems: true
      minItems: 1
      maxItems: 20

    DataProviders:
      description: optional list of multiaddrs known to provide the data
      type: array
      items:
        type: string
      uniqueItems: true
      minItems: 0
      maxItems: 20

    Meta:
      description: optional metadata
      type: object
      additionalProperties:
        type: string

    Error:
      description: base error object
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
        message:
          type: string

  parameters:

    skip:
      description: number of items to skip
      name: skip
      in: query
      required: false
      schema:
        type: integer
        format: int32
        default: 0

    limit:
      description: max records to return
      name: limit
      in: query
      required: false
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 1000
        default: 1000

    cid:
      description: return pin objects for the specified CID(s)
      name: cid
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
        uniqueItems: true
        minItems: 1
        maxItems: 1000
      style: form # ?cid=Qm1,Qm2,bafy3
      explode: false
      examples:
        oneId:
          summary: example of a single CID
          value: [QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR]   # ?cid=Qm
        multipleIds:
          summary: example of multiple CIDs
          value: [QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR,bafkreigtdgsgv2f3bkhsmxvku3bpnnqzubcxeupf7fff5f7l7tlm2v237a]   # ?cid=Qm,bafy

    status:
      description: return pin objects for pins with the specified status
      name: status
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/Status'

    auth:
      description: optional auth token (alternative to Authorization header)
      name: auth
      in: query
      required: false
      schema:
        type: string

  responses:
    BadRequest:
      description: Bad request (400)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    Unauthorized:
      description: Unauthorized (401)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    NotFound:
      description: The specified resource was not found (404)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    InsufficientFunds:
      description: Insufficient funds (409)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    InternalServerError:
      description: Internal server error (500)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  securitySchemes:
    tokenAuth:
      type: http
      scheme: bearer
security:
  - tokenAuth: []