RFC - API Endpoints for a Registry Server

[gamemaker1]

I would like to propose the following API endpoints for a registry server for consideration. This is an improvement over the Sunbird RC specification as given here.

The proposed specification is located here.

---

RFC - Registry Server APIs

Proposal for improvements submitted to the Sunbird RC project.

See the document on entity representations for a detailed explanation on all the JSON objects returned from API requests.

API Endpoints

Create An Entity

Request

POST /api/{entity-kind}

Parameters

Name	Type	In	Description
content-type	string	header	Recommended to set to application/json
accept	string	header	Recommended to set to application/vnd.registry.v1+json
entity-kind	string	path	The kind of entity to create
claims	array	body	An array of claims made by the entity

Usage

curl \
	--request POST \
	--header 'content-type: application/json' \
	--header 'accept: application/vnd.registry.v1+json' \
	--data-raw '{
		"claims": [
			{
				"id": "{registry-url}/api/{entity-kind}/{entity-id}/{entity-claim}",
				"value": "..."
			}
		]
	}' \
	'{registry-url}/api/{entity-kind}/'

Response

HTTP/1.1 201 CREATED
server: {registry-url}
content-type: application/json
x-registry-media-type: registry.v1; format=json

{
	"context": {
		"baseUrl": "{registry-url}",
		"schemas": ["https://registries/schemas/entity.json"]
	},
	"id": "{registry-url}/api/{entity-kind}/{entity-id}",
	"kind": "{registry-url}/api/{entity-kind}",
	"claims": [
		{
			"id": "{registry-url}/api/{entity-kind}/{entity-id}/{entity-claim}",
			"value": "..."
		}
	],
	"attestations": [],
	"metadata": {
		"created": "...",
		"lastUpdated": "..."
	}
}

Retrieve An Entity

Request

GET /api/{entity-kind}/{entity-id}

Parameters

Name	Type	In	Description
content-type	string	header	Recommended to set to application/json
accept	string	header	Recommended to set to application/vnd.registry.v1+json
entity-kind	string	path	The kind of entity to retrieve
entity-id	array	path	ID of the entity to retrieve

Usage

curl \
	--request GET \
	--header 'content-type: application/json' \
	--header 'accept: application/vnd.registry.v1+json' \
	'{registry-url}/api/{entity-kind}/{entity-id}'

Response

HTTP/1.1 200 OK
server: {registry-url}
content-type: application/json
x-registry-media-type: registry.v1; format=json

{
	"context": {
		"baseUrl": "{registry-url}",
		"schemas": ["https://registries/schemas/entity.json"]
	},
	"id": "{registry-url}/api/{entity-kind}/{entity-id}",
	"kind": "{registry-url}/api/{entity-kind}",
	"claims": ["..."],
	"attestations": ["..."],
	"metadata": {
		"created": "...",
		"lastUpdated": "..."
	}
}

Update An Entity

Request

PATCH /api/{entity-kind}/{entity-id}

Parameters

Name	Type	In	Description
content-type	string	header	Recommended to set to application/json
accept	string	header	Recommended to set to application/vnd.registry.v1+json
entity-kind	string	path	The kind of entity to create
entity-id	string	path	ID of the entity to update
claims	array	body	An array of claims that will replace the existing claims

Usage

curl \
	--request PATCH \
	--header 'content-type: application/json' \
	--header 'accept: application/vnd.registry.v1+json' \
	--data-raw '{
		"claims": [
			{
				"id": "{registry-url}/api/{entity-kind}/{entity-id}/{entity-claim}",
				"value": "..."
			}
		]
	}' \
	'{registry-url}/api/{entity-kind}/{entity-id}'

Response

HTTP/1.1 200 OK
server: {registry-url}
content-type: application/json
x-registry-media-type: registry.v1; format=json

{
	"context": {
		"baseUrl": "{registry-url}",
		"schemas": ["https://registries/schemas/entity.json"]
	},
	"id": "{registry-url}/api/{entity-kind}/{entity-id}",
	"kind": "{registry-url}/api/{entity-kind}",
	"claims": [
		{
			"id": "{registry-url}/api/{entity-kind}/{entity-id}/{entity-claim}",
			"value": "..."
		}
	],
	"attestations": ["..."],
	"metadata": {
		"created": "...",
		"lastUpdated": "..."
	}
}

Delete An Entity

Request

DELETE /api/{entity-kind}/{entity-id}

Parameters

Name	Type	In	Description
content-type	string	header	Recommended to set to application/json
accept	string	header	Recommended to set to application/vnd.registry.v1+json
entity-kind	string	path	The kind of entity to retrieve
entity-id	array	path	ID of the entity to delete

Usage

curl \
	--request DELETE \
	--header 'content-type: application/json' \
	--header 'accept: application/vnd.registry.v1+json' \
	'{registry-url}/api/{entity-kind}/{entity-id}'

Response

HTTP/1.1 204 NO CONTENT
server: {registry-url}
content-type: application/json
x-registry-media-type: registry.v1; format=json

{}

Attest A Claim

Request

POST /api/{entity-kind}/{entity-id}/{entity-claim}/attest

Parameters

Name	Type	In	Description
content-type	string	header	Recommended to set to application/json
accept	string	header	Recommended to set to application/vnd.registry.v1+json
entity-kind	string	path	The kind of entity whose claims to attest
entity-id	string	path	The ID of the entity whose claims to attest
entity-claim	string	path	The ID of the claim to attest
attestor	string	body	The ID of the entity attesting the claim
value	string	body	The attested value of the claim

Usage

curl \
	--request POST \
	--header 'content-type: application/json' \
	--header 'accept: application/vnd.registry.v1+json' \
	--data-raw '{
		"attestor": "{registry-url}/api/{entity-kind}/{entity-id}",
		"value": "..."
	}' \
	'{registry-url}/api/{entity-kind}/{entity-id}/{entity-claim}/attest'

Response

HTTP/1.1 200 OK
server: {registry-url}
content-type: application/json
x-registry-media-type: registry.v1; format=json

{
	"context": {
		"baseUrl": "{registry-url}",
		"schemas": ["https://registries/schemas/entity.json"]
	},
	"id": "{registry-url}/api/{entity-kind}/{entity-id}",
	"kind": "{registry-url}/api/{entity-kind}",
	"claims": [
		{
			"id": "{registry-url}/api/{entity-kind}/{entity-id}/{entity-claim}",
			"value": "..."
		}
	],
	"attestations": [
		{
			"attestor": "{registry-url}/api/{entity-kind}/{entity-id}",
			"date": "...",
			"claims": ["{registry-url}/api/{entity-kind}/{entity-id}/{entity-claim}"],
			"signature": {
				"type": "https://registries/signature-types/jws-rsa256",
				"keyId": "{registry-url}/meta/signing-keys/{key-id}",
				"value": "..."
			}
		}
	],
	"metadata": {
		"created": "...",
		"lastUpdated": "..."
	}
}

Retrieve An Entity's Schema

Request

GET /api/{entity-kind}

Parameters

Name	Type	In	Description
content-type	string	header	Recommended to set to application/json
accept	string	header	Recommended to set to application/vnd.registry.v1+json
entity-kind	string	path	The kind of entity whose schema to retrieve

Usage

curl \
	--request GET \
	--header 'content-type: application/json' \
	--header 'accept: application/vnd.registry.v1+json' \
	'{registry-url}/api/{entity-kind}'

Response

HTTP/1.1 200 OK
server: {registry-url}
content-type: application/json
x-registry-media-type: registry.v1; format=json

{
	"context": {
		"baseUrl": "{registry-url}",
		"schemas": ["https://registries/schemas/schema.json"]
	},
	"kind": "{registry-url}/api/{entity-kind}",
	"claims": [
		{
			"id": "{registry-url}/api/{entity-kind}/{entity-id}/{entity-claim}",
			"value": "...",
			"attestationPolicy": {
				"attestorKind": "{registry-url}/api/{attestor-kind}",
				"condition": "{ATTESTOR}.{entity-claim} == {ENTITY}.{entity-claim}"
			}
		}
	]
}

Search For An Entity

Request

GET /api/{entity-kind}/search

Parameters

Name	Type	In	Description
content-type	string	header	Recommended to set to application/json
accept	string	header	Recommended to set to application/vnd.registry.v1+json
entity-kind	string	path	The kind of entities to search
query	string	body	The query to search through entities

Usage

curl \
	--request GET \
	--header 'content-type: application/json' \
	--header 'accept: application/vnd.registry.v1+json' \
	--data-raw '{
		"query": {
			"claims": [
				{
					"id": "{registry-url}/api/{entity-kind}/{entity-id}/{entity-claim}",
					"value": "..."
				}
			],
			"attestations": [
				{
					"attestor": "{registry-url}/api/{entity-kind}/{entity-id}"
				}
			]
		}
	}' \
	'{registry-url}/api/{entity-kind}/search'

Response

HTTP/1.1 200 OK
server: {registry-url}
content-type: application/json
x-registry-media-type: registry.v1; format=json

{
	"context": {
		"baseUrl": "{registry-url}",
		"schemas": ["https://registries/schemas/schema.json"]
	},
	"kind": "{registry-url}/api/{entity-kind}",
	"claims": [
		{
			"id": "{registry-url}/api/{entity-kind}/{entity-id}/{entity-claim}",
			"value": "..."
		}
	]
}

Retrieve Signing Keys

Request

GET /meta/signing-keys/{key-id}

Parameters

Name	Type	In	Description
content-type	string	header	Recommended to set to application/json
accept	string	header	Recommended to set to application/vnd.registry.v1+json
key-id	array	path	ID of the key to retrieve

Usage

curl \
	--request GET \
	--header 'content-type: application/json' \
	--header 'accept: application/vnd.registry.v1+json' \
	'{registry-url}/meta/signing-keys/{key-id}'

Response

HTTP/1.1 200 OK
server: {registry-url}
content-type: application/json
x-registry-media-type: registry.v1; format=json

{
	"context": {
		"baseUrl": "{registry-url}",
		"schemas": ["https://registries/schemas/signing-key.json"]
	},
	"id": "{registry-url}/meta/signing-keys/{key-id}",
	"kind": "https://registries/key-types/{key-type}",
	"publicKey": "..."
}

[pramodkvarma]

There are two types of APIs (one internal to registries which Sunbird RC implementation can use as default) and second set of APIs that are exposed to "verifiers" and "attesters" who are outside parties who will integrate with a registry.

For latter use the Google doc created by Rahul Kulkarni to help finalize.

For former (internal APIs of Sunbird RC), I suggest you work with @dileepbapat and @tejash-jl. Remember that there are live implementations of Sunbird RC in India and in other countries. So, any core API changes should be backward compatible.

[rahul101001000]

I've updated the Draft Technical Spec Google Doc incorporating suggestions from the RFC by @gamemaker1 and balancing it with current implementation. Please do take a look at section 6 and comment, especially on items in red where spec may differ from implementation.

@pramodkvarma @dileepbapat @tejash-jl @kesavanp123 @gamemaker1 @bharatkashyap