Skip to main content

Service and link specifications API

A service specification defines a service: the attributes a developer fills in, the actions that run on it, and how scopes can link to it. Everything in this section is what a platform team crafts. The instances created from it live in the Service and link API.

How the endpoints nest​

Specifications form a tree. A service specification owns action specifications and link specifications, and each link specification owns its own action specifications. Every specification, link and action also keeps an append-only history of snapshots, which packages pin.

service_specification
├── action_specification          service actions: create, update, delete, custom
├── link_specification
│   └── action_specification      link actions: link, unlink, custom
└── snapshots                     one history per specification, link and action
EntityEndpointsNested underWhere to find it
Service specification/service_specification, /service_specification/{id}Nothing, it's the rootThis page
Link specifications of a specification/service_specification/{id}/link_specificationService specificationThis page
Snapshots/{service,link,action}_specification/{id}/snapshots, plus /{snapshotId}Each specification, link or actionThis page, Link specification and Action specification
Package a specification/service_specification/{id}/packageService specificationThis page, then the Package API
Link specification/link_specification, /link_specification/{id}Service specification, through specification_idLink specification
Service action specification/service_specification/{serviceSpecificationId}/action_specification, plus /{id}Service specificationService action specification
Link action specification/link_specification/{linkSpecificationId}/action_specification, plus /{id}Link specificationLink action specification
Any action specification/action_specification, /action_specification/{id}, /action_contextReads across both kindsAction specification

A typical flow​

  1. Create the specification with POST /service_specification: its name, who can see it (visible_to), and the JSON schema of its attributes. With use_default_actions, nullplatform creates the create, update and delete actions for you.
  2. Add its actions under /service_specification/{serviceSpecificationId}/action_specification, one per operation the service supports beyond the defaults.
  3. Describe how scopes link to it with POST /link_specification, then add the link's own actions under /link_specification/{linkSpecificationId}/action_specification.
  4. Version it. Every change mints a snapshot. To freeze a set of snapshots together with the image or repository that implements them, package the specification with POST /service_specification/{id}/package and continue in the Package API. Specification reads accept package_revision_id to return exactly what a package revision pins.

Endpoints​