freshy969/entities-api-docs

Documentation for the https://entities.paylike.io service.

Pawns API

• Basics
• Identities
  • Create an identity
• Privileges
  • Create a privilege
• Entities
  • Create an entity
  • Fetch an entity
• Residences
  • Create a residence
  • Fetch a residence
  • Search residences
• Links
  • Create a link
  • Search links
• Relationships
  • Create a relationship
  • Search relationships
• Documents
  • Create a document
  • Fetch a document
  • Search documents
• Files
  • Create (upload) a file
  • Fetch (download) a file

Basics

This API is exposed using the HTTP protocol.

The API is immutable meaning updates are not supported and any change in the data should be represented by a new entity.

Request

Any response body must be either JSON encoded with a Content-Type header set to application/json or binary with a corresponding Content-Type (e.g. for file uploads).

Authentication and authorization

Most endpoints require you to authenticate. [Create an identity](#create-an- identity) to get an API key.

Supply an API key as the username part of a HTTP basic authentication.

Authorization: Basic $(echo $API_KEY | base64)

Using cURL:

curl -i -u $API_KEY https://pawns/entities/ping

Response

All successful responses will have status codes in the 200-299 range.

The content type, if data is returned, will be application/x-ndjson; charset=utf-8. NDJSON simply means JSON but with top level arrays delimited by newlines.

Error codes:

400 Validation error
401 Missing or unknown API key
403 Forbidden (API key OK, but no access)
404 Unknown URL

Create

Use the HTTP POST method to submit data.

curl -i https://pawns/entities \
	-H 'Content-Type: application/json' \
	-d <data>

Attributes marked with * in these docs are required.

A successful request will return a 201 status code and data with a format of:

{
	id: String,
}

Fetch

Use the HTTP GET method to fetch data.

curl -i https://pawns/entities/$ID \
	-H 'Accept-Type: application/x-ndjson'

A successful request will return a 200 status code.

Most responses will include an id which is system-wide unique, and a creatorId referencing the identity who added the data. The date of creation can be extracted from the ID (see this example).

Identities

Create an identity

/identities

This endpoint accepts no data.

Returns:

{
	id: String,
	creatorId: String,
	key: String,
}

Privileges

Create a privilege

So far only a single type of privilege exists. Thus having a privilege implicitly means read and write access to an entity.

/privileges

{
	identityId: String*,	// existing identity ID
	entityId: String*,		// existing entity ID
}

To create a new privilege, the authenticated identity must itself have a privilege for the same entity.

Entities

Create an entity

/entities

Set one of individual or corporation to true.

{
	// mutually exclusive
	individual: Boolean,
	corporation: Boolean,

	name: String,			// legal name (max length: 256)

	// registered birth or official incorporation
	birth: {
		// optional as a whole
		date: {
			year: Number*,	// four digits year
			month: Number*,	// month (1-12)
			day: Number*,	// day (1-31)
		},

		country: String,	// ISO 3166-1 alpha2 code
	},
}

Creating an entity automatically adds a privilege of the creating identity and the new entity.

Fetch an entity

/entities/:id

Residences

Create a residence

/residences

{
	entityId: String*,	// existing entity ID
	domicile: Boolean,	// headquarter, primary address
	address: String,	// official address (max length: 512)
	country: String,	// ISO 3166-1 alpha2 code
}

Fetch a residence

/residences/:id

Search residences

/residences?entityId=:entityId

entityId is required.

Links

Provides a way of linking an entity to external registries such as business registries or social security systems.

Create a link

/links

{
	entityId: String*,	// existing entity ID
	system: {
		id: String*,	// identifier of the external system (length: 1-64)
		key: String*,	// primary key in the external system (length: 1-128)
	},
}

Search links

/links?entityId=:entityId

entityId is required.

Relationships

Relationships are a way to describe how two entities are related. Notice that entities might have multiple relationships e.g. when related in more than one way.

Create a relationship

{
	entities: Array*,	// array of existing entity IDs (length: 2)
	type: String*,		// nature of relationship (length: 1-64)
}

An example type would be owner in which case entities[0] would be an owner of entities[1].

Search relationships

/links?entityId=:entityId

entityId is required.

Documents

Create a document

/documents

{
	entityId: String*,		// existing entity ID
	fileId: String*,		// existing file ID (UUID)

	// optional
	tags: Array(String),	// max length: 16, strings length: 1-64

	// specifies that this document is related somehow to a residence, it
	// might be a "proof of address".
	residenceId: String,	// existing residence ID
}

Fetch a document

/documents/:id

Returns:

{
	id,
	creatorId,
	created,
	entityId,
	residenceId,
	tags,

	file: {
		id,
		type,
		name,
	},
}

Search documents

/documents?
	entityId
	residenceId

entityId is required.

Files

Create (upload) a file

/files

Requires a Content-Type HTTP header with the media/mime type of the file (e.g. image/jpeg).

Optional HTTP headers:

X-Filename		# URI encoded name of file

URI encoding as per encodeURIComponent.

Expects the request body to be the binary data

Fetch (download) a file

/files/:id