Pinning Service API Spec

This repository contains the specs for the vendor-agnostic pinning service API for the IPFS ecosystem

• About
• Specification
  • Code generation (client/server)
• Adoption
  • Client libraries
  • Server implementations
  • Online services
• Contribute

About

A pinning service is a service that accepts CIDs from a user in order to host the data associated with them.

The rationale behind defining a generic pinning service API is to have a baseline functionality and interface that can be provided by pinning services, so that tools can be built on top of a common base of functionality.

In this presentation, IPFS creator Juan Benet discusses current and potential pinning use cases, and how a standardized IPFS pinning API can meet these envisioned needs.

The API spec in this repo is the first step towards that future.

Specification

This API is defined as an OpenAPI spec in YAML format:

• ipfs-pinning-service.yaml

Documentation

You can find human-readable API documentation generated from the YAML file here:

• https://ipfs.github.io/pinning-services-api-spec

Code generation

https://openapi-generator.tech allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically, given the OpenAPI spec at ipfs-pinning-service.yaml.

Give it a try before you resort to implementing things from scratch.

Adoption

Built-in support for pinning services exposing this API is coming to IPFS tooling:

• go-ipfs (since v0.8.0: ipfs pin remote --help, see how to work with remote pinning services)
• js-ipfs-http-client (ipfs.pin.remote.* JS APIs)
• ipfs-cluster (issue)
• js-ipfs – (js-ipfs/pull/3588)
• ipfs-webui (remote pin support since v2.12.0)
• ipfs-desktop (>0.20.x)

Client libraries

• js-pinning-service-http-client
  An IPFS Pinning Service HTTP Client library for JS, used in compliance test suite.
• go-pinning-service-http-client
  An IPFS Pinning Service HTTP Client library for Go, used by go-ipfs internally in ipfs pin remote --help commands.
• https://openapi-generator.tech/docs/generators#client-generators
  Use YAML file to generate client for your language

Server implementations

• https://github.com/ipfs/ipfs-cluster Pinset orchestration for IPFS – tracking issue
• https://github.com/ipfs-shipyard/js-mock-ipfs-pinning-service
  Implementation of in-memory service for testing purposes
• https://github.com/ipfs-shipyard/rb-pinning-service-api
  A Rails app that implements the IPFS Pinning Service API
• https://openapi-generator.tech/docs/generators#server-generators
  Use YAML file to generate server boilerplate for your language

CI/CD

• https://github.com/marketplace/actions/ipfs-remote-pinning
  IPFS Pinning GitHub Action that adds data to IPFS and pins it to any ENDPOINT compatible with Pinning Service API

Online services

• https://pinata.cloud – (documentation)
  • ipfs pin remote service add pinata https://api.pinata.cloud/psa YOUR_JWT
• https://estuary.tech – (documentation)
  • ipfs pin remote service add estuary https://api.estuary.tech/pinning/ YOUR_API_KEY
• https://web3.storage – (documentation)
  • ipfs pin remote service add web3-storage https://api.web3.storage/ YOUR_API_KEY
• https://nft.storage
  • ipfs pin remote service add nft-storage https://nft.storage/api YOUR_API_KEY
• {your project could be here} – open a PR!

Timeline

• 2022 Q1
  • web3.storage API support: https://docs.web3.storage/how-tos/pinning-services-api
  • estuary.tech API support: https://docs.estuary.tech/pinning-list
  • Mock server for local development: https://github.com/ipfs-shipyard/js-mock-ipfs-pinning-service
  • WIP official API client for JS: https://github.com/ipfs-shipyard/js-pinning-service-http-client/
  • WIP compliance test suite: #64
  • WIP ipfs-cluster support (commit)
• 2021 Q1
  • go-ipfs 0.8.0 shipped with built-in client for v1.0.0 of this API
  • Pinata announces endpoint compatible with this spec: https://pinata.cloud/documentation#PinningServicesAPI
  • ipfs-webui v2.12.0 provides UI based on pin remote commands
  • Textile is working on Bucket Pinning API
• 2020 Q3
  • IPFS GUI WG working on adding support for pinning services into IPFS Desktop/Web UI:
    • Epic: Pinning service integration · Issue #91 · ipfs/ipfs-gui
    • Analysis of remote pinning services vs the needs of IPFS Web UI
  • ipfs/pinning-services-api-specs is created as a place for stakeholders to collaborate and finalize the API
    • 2020-07-14: Spec in draft status is ready for implementation
    • 2020-08: Addressing feedback from early implementers
    • 2020-09: End-to-end testing
• 2020 Q2
  • Pinning Summit 2020 (website, recorded talks)
• 2019 Q2
  • Creation of a generic pinning service API proposed in ipfs/notes/issues/378

Contribute

Suggestions, contributions, and criticisms are welcome! However, please make sure to familiarize yourself deeply with IPFS, the models it adopts, and the principles it follows.

This repository falls under the IPFS Code of Conduct.

Spec lifecycle

We use the following label system to identify the state of aspects of this spec:

• — A work-in-progress, possibly to describe an idea before actually committing to a full draft of the spec
• — A draft that is ready to review, and should be implementable
• — A spec that has been adopted (implemented) and can be used as a reference to learn how the system works
• — We consider this spec to close to final; it might be improved, but the system it specifies should not fundamentally change
• — This spec will not change
• — This spec is no longer in use