API Reference - Dependencies Service

post | put | head | get

Key Concepts

What are Dependencies?

Dependencies are reference data needed to decode a stream or providing additional context.

Publishing dependencies outside the stream allows streams to extend beyond the retention time for a topic, and for consumers to pick up a stream mid-way through without reading from the start.

Two important types of dependencies are:

dataFormat

Describes the layout of parameters in telemetry data messages.

atlasConfiguration

Describes the ATLAS parameter tree, data conversions, etc.
Required by the ATLAS 10 streaming recorder.

Applications will typically publish dependencies on startup, but they can be pre-published if the dependencies are effectively static, as might be the case for a sensor board.

Group, Type and Id

group

Namespace providing separation by environment, team, etc.
Future versions of the service may leverage groups for additional security.
Groups must be whitelisted in service configuration. The pre-configured group is: dev

type

Type of dependency, which must be whitelisted in service configuration.
The pre-configured types are: dataFormat & atlasConfiguration

id

Identifier, unique within the group and type.
The service is capable of generating dependency ids from content, if required.

All three tokens must conform to this regular expression:

^[A-Za-z0-9{}_-]{1,64}$

API

Base URI: http://localhost:8180/api/dependencies

Put and generate id for Dependency

POST /{group}/{type}

Parameters:

• group: typically the name of an environment or team
• type: dependency type

Headers:

Indicate the Content-Type to allow canonicalization:

• Content-Type:
  
  • application/json
  • text/plain; charset=UTF-8
  • application/xml
  • application/octet-stream

Body:

• Dependency content

Returns:

• 201 Created, on success, if the dependency did not already exist
• 200 OK, on success, if the dependency already existed (not considered an error)
• 400 Bad Request, if the group or type is invalid

x-dependency-id header indicates the generated dependency id, on success.

Put Dependency with a specific id

PUT /{group}/{type}/{id}

Parameters:

• group: typically the name of an environment or team
• type: dependency type
• id: dependency id

Body:

• Dependency content

Returns:

• 201 Created, on success, if the dependency did not already exist
• 200 OK, on success, if the dependency already existed (not considered an error)
• 400 Bad Request, if the group, type or id is invalid

Has Dependency check

HEAD /{group}/{type}/{id}

Parameters:

• group: typically the name of an environment or team
• type: dependency type
• id: dependency id

Returns:

• 200 OK, if the dependency exists
• 404 Not Found, if the dependency does not exist or you do not have permission to access it
• 400 Bad Request, if the group, type or id is invalid

Get Dependency

GET /{group}/{type}/{id}

Parameters:

• group: typically the name of an environment or team
• type: dependency type
• id: dependency id

Returns:

• 200 OK, if the dependency exists
• 404 Not Found, if the dependency does not exist or you do not have permission to access it
• 400 Bad Request, if the group, type or id is invalid

Body is Dependency content