pins.yml

openapi: '3.0.2'
info:
  title: Axis Pinning Service
  version: '0.0.1'
  description: |
    Implements IPFS pinning services API spec: [github.com/ipfs/pinning-services-api-spec](https://github.com/ipfs/pinning-services-api-spec)
servers:
  - url: https://api.server.test/v1
paths:
  /pins:
    get:
      summary: List of pin objects
      description: |
        List all the pin objects, matching optional filters; when no filter is
        provided, only successful pins are returned
      tags:
        - pins
      security:
        - accessToken: []
      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'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/sort'
      responses:
        '200':
          description: OK
          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'
    post:
      summary: Add pin object
      description: Add a new pin object for the current access token
      tags:
        - pins
      security:
        - accessToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $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'
  /pins/{requestid}:
    parameters:
      - name: requestid
        in: path
        required: true
        schema:
          type: string
        description: |
          Unique identifier of the pin object
    get:
      summary: Get pin object
      description: Get a pin object and its status
      tags:
        - pins
      security:
        - accessToken: []
      responses:
        '200':
          description: OK
          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'
    put:
      summary: Update pin object
      description: Update an existing pin object.
      tags:
        - pins
      security:
        - accessToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $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'
    post:
      summary: Update pin object
      description: |
        Same as PUT /pins/{requestid}. POST included to meet IPFS Pin Service API
        specification.
      tags:
        - pins
      security:
        - accessToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $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'
    patch:
      summary: Modify pin object
      description: |
        Modify an existing pin object.
      tags:
        - pins
      security:
        - accessToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $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
      security:
        - accessToken: []
      responses:
        '202':
          description: Accepted
        '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'

components:
  schemas:
    PinResults:
      description: |
        Response used for listing pin objects matching request
      type: object
      required:
        - count
        - total
        - results
      properties:
        count:
          description: |
            The total number of pin objects that exist for passed query filters
          type: integer
          format: int32
          minimum: 0
          example: 1
        total:
          description: |
            The total number of pin objects without 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 ID of the pin request; can be used to check the
            status of ongoing pinning, modification of pin object, or pin
            removal
          type: string
          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:28Z"
        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: 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: 'my precious data'
        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 for
        transferring any new data from external peers
      type: array
      items:
        type: string
      uniqueItems: true
      minItems: 1
      maxItems: 20
      example: ['/dnsaddr/pin-service.example.com']
    Origins:
      description: Optional list of multiaddrs known to provide the data
      type: array
      items:
        type: string
      uniqueItems: true
      minItems: 0
      maxItems: 20
      example: ['/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: |
        Text matching strategy. Values prefixed with an 'i' indicate
        case-insensitivity
      type: string
      default: exact
      enum:
        - exact
        - iexact
        - partial
        - ipartial
    Error:
      description: Base error object
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - reason
          properties:
            reason:
              type: string
              description: Identifying title of the error
              example: "SOME_ERROR_REASON"
            details:
              type: string
              description: An optional, longer description of the error
              example: Some error occured and here are some description about it.

  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:28Z"
    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:28Z"
    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)
      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
    name:
      description: |
        Return pin objects with names that contain provided value (partial or
        full match)
      name: name
      in: query
      required: false
      schema:
        type: string
        maxLength: 255
      example: "my precious"
    status:
      description: Return pin objects for pins with the specified status
      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
    meta:
      description: Return pin objects that match specified metadata
      name: meta
      in: query
      required: false
      content:
        application/json: # ?meta={"foo":"bar"}
          schema:
            $ref: '#/components/schemas/PinMeta'
    match:
      description: Text matching strategy for the 'name' parameter
      name: match
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/TextMatchingStrategy'
    offset:
      description: Return pin objects starting at given offset records
      name: offset
      in: query
      required: false
      schema:
        type: integer
        format: int32
        example: 100
        default: 0
    sort:
      description: |
        Return pin objects sorted by the given field. A unary negative may be
        used to order by descending order.
      name: sort
      in: query
      required: false
      schema:
        type: string
        default: created
        enum:
          - cid
          - created
          - name
          - status
        uniqueItems: true
        minItems: 1
      style: form # ?sort:cid,name
      explode: false

  responses:
    BadRequest:
      description: Bad request (400)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized (401); access token is missing or invalid
      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:
    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