ShiftNrg/pinning-services-api-spec

New vendor-agnostic Pinning Service API for IPFS ecosystem

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 in Q3:

• go-ipfs / js-ipfs (CLI/HTTP API)
• ipfs-desktop / ipfs-webui (GUIs)

Client libraries

• go-pinning-service-http-client
  An IPFS Pinning Service HTTP Client library for Go

Server implementations

• https://github.com/ipfs-shipyard/rb-pinning-service-api
  A Rails app that implements the IPFS Pinning Service API

Online services

• {your project could go here}
  We are currently working with pinning services to expose this API — so stay tuned!

Timeline

• 2019 Q2
  • Creation of a generic pinning service API proposed in ipfs/notes/issues/378
• 2020 Q2
  • Pinning Summit 2020 (website, recorded talks)
• 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

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