Skip to main content

Dependencies

One of the most powerful features of Cortex is the ability to define dependencies on other services. This powers many features, including automated notifications to service owners when a dependency deprecates its API or makes backwards incompatible changes.

Service Registration

Service Descriptor

The x-cortex-dependency field allows you to define a list of dependencies. A dependency may be directed towards a service, or more granularly, to a specific endpoint on that service.

info:
x-cortex-dependency:
- tag: braavos
method: GET
path: /2.0/users/{username}
description: ensure user has payment information configured
metadata:
tags:
- billing
- identity
prod: true
FieldDescriptionOptional?
tagThe tag of the service this depends on. See x-cortex-tagNo
methodHTTP method if depending on a specific endpointRequired if path is present
pathThe actual endpoint (as defined in the OpenAPI file) this service depends onRequired if method is present
descriptionA description of the dependency.Yes
metadataJSON metadata tags for the relationship. Supports arbitrary objects.Yes

API

See API Docs for authentication details.

YAML is the source of truth

If a dependency has already been set through the Service Descriptor, the API will return an error.

endpoints are optional

A service dependency optionally references an endpoint (method and path) in the callee service. If no endpoint is referenced it is assumed that the caller service depends on all endpoints of the callee service.

For all requests method or path are optional, however if one is present the other must also be present.

When interactring with an existing dependency the method and path must be specified correctly to identify it.

FieldDescriptionOptional?
callerTagThe tag of the service.No
calleeTagThe tag of the service the caller depends on.No
methodHTTP method if depending on a specific endpointRequired if path is present
pathThe actual endpoint (as defined in the OpenAPI file) this service depends onRequired if method is present
descriptionA description of the dependency.Yes
metadataJSON metadata tags for the relationship. Supports arbitrary objects.Yes
{
"callerTag": "my-service",
"calleeTag": "braavos",
"path": "/2.0/users/{username}",
"method": "GET",
"description": "ensure user has payment information configured",
"metadata": {
"tags": ["billing", "identity"],
"prod": true
}
}

Create a Dependency

POST /api/v1/services/{caller-tag}/dependencies/{callee-tag}?method={method}&path={path}

{
"description": "ensure user has payment information configured",
"metadata": {
"tags": ["billing", "identity"],
"prod": true
}
}

Retrieve a Dependency

GET /api/v1/services/{caller-tag}/dependencies/{callee-tag}?method={method}&path={path}

Update a Dependency

PUT /api/v1/services/{caller-tag}/dependencies/{callee-tag}?method={method}&path={path}

PUT replaces entire object

The request body is considered a modified version of the already existing entity. Leaving a field out of the JSON will be interpreted as null.

{
"description": "ensure user has payment information configured",
"metadata": {
"tags": ["billing", "identity"],
"prod": false
}
}

Delete a Dependency

DELETE /api/v1/services/{caller-tag}/dependencies/{callee-tag}?method={method}&path={path}

Bulk Create or Update Dependencies

PUT /api/v1/services/dependencies

PUT replaces entire object

The request body is considered a modified version of the already existing entity. Leaving a field out of the JSON will be interpreted as null.

{
"values": {
"my-service": [
{
"tag": "braavos",
"path": "/2.0/users/{username}",
"method": "GET",
"description": "ensure user has payment information configured",
"metadata": {
"tags": ["billing", "identity"],
"prod": true
}
}
],
"my-other-service": [
{
"tag": "my-service",
"path": "/1.0/widget/{id}",
"method": "GET",
"description": "get widget",
"metadata": {
"tags": ["widget"],
"prod": true
}
}
]
}
}