Overview

URI
Following REST API conventions are followed for Resource URIs:
Operations for an entity are available through the Resource URI as a collection .../api/<version>/entities. Plural of the entity name is used as the collection name - example.../api/v1/users.
Trailing forward slash is not used in the endpoint URI. Example use .../api/v1/databases instead of .../api/v1/databases/.
Resource URI for an entity instance by the entity id is .../api/v1/entities/{id}. Resource URI for an entity instance by name is .../api/v1/entities/name/{name}.
Resource representation
The REST API calls return a response with JSON Content-Type and Content-Length that includes the length of the response.
All responses include the Resource ID field even though theidwas provided in the request to simplify the consumption of the response at the client.
Entity names and field names use camelCase per Javascript naming convention.
All resources include an attributehrefwith Resource URI. All relationship fields of an entity will also includehreflinks to the related resource for easy access.
Unknown fields sent by the client in API requests are not ignored to ensure the data sent by the client is not dropped at the server without the user being aware of it.
HTTP methods
Following HTTP methods are supported for CRUD operations. HTTP response codes are used per REST API conventions.
HTTP Methods
Response
GET .../api/v1/entities
List entities
GET .../api/v1/entities/{id}
Get an entity by id
GET .../api/v1/entities/name/{name}
Get an entity by name
POST .../api/v1/entities
Create an entity
PUT .../api/v1/entities/{id}
Create or update an entity
PATCH .../api/v1/entities/{id}
Update an entity using JSONPatch​
DELETE .../api/v1/entities/{id}
Delete an entity
GET Operations
Listing entities
GET operation returns a list of entities as shown below:
1
GET /v1/tables
Copied!
1
200 OK
2
​
3
{
4
  “data” : [
5
    {
6
      “id”: “123e4567-e89b-42d3-a456-556642440000”
7
      “name”: “dim_user”,
8
      “documentation” : “This table has user information...”
9
    },
10
    {
11
      “id”: “4333e4567-e89b-42d3-a456-556642440000”
12
      “name”: “fact_sales”,
13
      “documentation” : “This table has sales information...”
14
    }
15
    ...
16
  ],
17
  "paging" : {
18
    "before" : null
19
    "after" : "2yXqpvzRNGUE"
20
  }
21
}
Copied!
Cursor-based pagination
List API requests may return a large number of results in a single response. Cursor-based pagination is supported to manage the number of results.
1
GET /v1/tables?limit=10&after=2yXqpvzRNGUE
Copied!
1
200 OK
2
​
3
{
4
  “data” : [
5
    ...
6
  ],
7
  "paging" : {
8
    "before" : "2ySdOiNaz",
9
    "after" : "2uiGDWxz=UV"
10
  }
11
}
Copied!
before: This cursor points to the start of the page of data that has been returned. Use thebeforecursor returned in the result in a subsequent request to scroll backwards. When response returns before as null, backward scrolling stops and you are at the beginning of the list.
after: This cursor points to the end of the page of data that has been returned. Use theaftercursor returned in the result in a subsequent request to scroll backwards. When response returns after as null, forward scrolling stops and you are at the end of the list.
limit: This is the maximum number of objects that may be returned.
Getting an entity by id or name
Using an identifier to identify a resource is a stable and unambiguous way of accessing the resource. Additionally, all resources support getting a resource by fully-qualified-name as shown below. These URLs are not stable and may not remain valid if the name of the entity changes.
1
GET /v1/tables/123e4567-e89b-42d3-a456-556642440000
Copied!
1
GET /v1/tables/name/service.database.dim_user
Copied!
1
200 OK
2
{
3
  “id”: “123e4567-e89b-42d3-a456-556642440000”
4
  “name”: “dim_user”,
5
  “documentation” : “This table has user information...”
6
  “columns” : [
7
    “column1”: {
8
      ...
9
    },
10
    “column2”: {
11
      ...
12
    }
13
    ...
14
  ]
15
  ...
16
}
Copied!
Getting entities with only necessary fields
To GET an entity with only necessary fields, passfieldsquery parameter while listing or getting an entity. This helps clients control the amount of data returned in the response. Some fields may be included by default whether fields specifies them or not (example - id and name fields below):
1
GET /v1/tables/123e4567-e89b-42d3-a456-556642440000?fields=columns,tableConstraints,usage
Copied!
1
200 OK
2
{
3
  “id”: “123e4567-e89b-42d3-a456-556642440000”
4
  “name”: “dim_user”,
5
  “documentation” : “This table has user information...”
6
  "columns": ...
7
  "usage": ...
8
  "tableConstraints": ...
9
}
Copied!
POST
HTTP POST method is used for creating new entities.
1
POST http://localhost:8585/api/v1/users
2
{
3
  “name”: “[email protected].com”
4
}
Copied!
1
201 Created
2
content-length: 151
3
content-type: application/json
4
{
5
  "id": "6feb5287-f3c5-457f-86ae-95bcfb82e867",
6
  "name": "[email protected]",
7
  "href": "http://localhost:8585/api/v1/users/6feb5287-f3c5-457f-86ae-95bcfb82e867"
8
}
Copied!
POST request usually takes a simpler request object with a smaller subset of fields compared to the entity object that could include lot more fields to keep the APIs simple.
Required fields in the request object are marked in the corresponding JSON schema.
When an entity is created, 201 Created the response is returned along with Entity data as JSON content.
PUT
A PUT request is used to update an entity or create an entity when it does not exist.
1
PUT http://localhost:8585/api/v1/users
2
​
3
{
4
  “name”: “[email protected].com”
5
}
Copied!
1
201 Created
2
content-length: 151
3
content-type: application/json
4
{
5
  "id": "6feb5287-f3c5-457f-86ae-95bcfb82e867",
6
  "name": "[email protected]",
7
  "href": "http://localhost:8585/api/v1/users/6feb5287-f3c5-457f-86ae-95bcfb82e867"
8
}
Copied!
PUT request usually takes a simpler request object with a smaller subset of fields compared to the entity object that could include lot more fields to keep the APIs simple.
Required fields in the request object are marked in the JSON schema.
When an entity is created, 201 Created the response is returned. If the entity already exists, the entity is replaced based on the PUT request and200 OKthe response is returned. Both responses include entity data as JSON content.
PATCH
PATCH request is used for updating an existing entity by sending a JSON patch document in the request.
1
PATCH http://localhost:8585/api/v1/users
2
​
3
[
4
  { "op": "replace", "path": "/displayName", "value": "First Last" },
5
  { "op": "remove", "path": "/owns/0" }
6
]
Copied!
1
200 OK
2
{
3
  "id": "6feb5287-f3c5-457f-86ae-95bcfb82e867",
4
  "name": "[email protected]",
5
  "href": "http://localhost:8585/api/v1/users/6feb5287-f3c5-457f-86ae-95bcfb82e867",
6
  “displayName” : “First Last”
7
}
Copied!
Client first gets Entity using a GET request. The fields are then updated with the new values. The JSON patch is generated by diffing the original and the updated JSON documents.
JSON diff is sent using a PATCH request.
When the diff is successfully applied on the server, 200 OK response is returned along with the updated entity data as content.
DELETE
DELETE request is used for deleting an existing entity. On successful deletion, the server returns 200 OK response.
1
DELETE http://localhost:8585/api/v1/users/6feb5287-f3c5-457f-86ae-95bcfb82e867
Copied!
1
200 OK
Copied!

Metadata Standard - Previous

APIs

API Organization

Last modified 6d ago

Copy link

Edit on GitHub

Contents

URI

Resource representation

HTTP methods

GET Operations

Listing entities

Getting an entity by id or name

Getting entities with only necessary fields