Changebase exposes a REST API for developing integrations. The API accepts both JSON encoded and form-encoded bodies. Response are JSON encoded.
Authentication
Changebase's API uses API keys to authenticate requests. API keys are associated with a database and all requests are scoped to that database.
Authentication can be performed via the Api-Key header or via HTTP Basic Auth, with the token as the username.
All API requests must be made over HTTPS. Requests made over HTTP will fail.
Request Parameters
All resources follow a standard query format, described below. This format allows for filtering, ordering, limiting, and including subresources.
Filtering
Filtering resources can be performed by including a query parameter based on the attribute being used to filter. For example, an event can be filtered based on the lsn. The table below shows all of the possible filters for the lsn attribute.
| URL Path | Query Params | JSON Request | Equivelent SQL | Response |
|---|---|---|---|---|
/events | `` | {} | SELECT * FROM events | [{…}, {…}] |
/events | where[lsn]=1, where[lsn][eq]=1 | { "where": { "lsn": 1 } }, { "where": { "lsn": { "eq": 1 } } } | SELECT * FROM events WHERE lsn = 1 | [{…}] |
/events | where[lsn][neq]=1 | { "where": { "lsn": { "neq": 1 } } } | SELECT * FROM events WHERE lsn != 1 | [{…}] |
/events | where[lsn][gt]=1 | { "where": { "lsn": { "gt": 1 } } } | SELECT * FROM events WHERE lsn > 1 | [{…}] |
/events | where[lsn][gte]=1 | { "where": { "lsn": { "gte": 1 } } } | SELECT * FROM events WHERE lsn >= 1 | [{…}] |
/events | where[lsn][lt]=1 | { "where": { "lsn": { "lt": 1 } } } | SELECT * FROM events WHERE lsn < 1 | [{…}] |
/events | where[lsn][lte]=1 | { "where": { "lsn": { "lte": 1 } } } | SELECT * FROM events WHERE lsn <= 1 | [{…}] |
/events | where[lsn][lt]=1 | { "where": { "lsn": { "lt": 1 } } } | SELECT * FROM events WHERE lsn < 1 | [{…}] |
/events | where[lsn][in][]=1&where[lsn][in][]=2 | { "where": { "lsn": { "in": [ 1, 2 ] } } } | SELECT * FROM events WHERE lsn IN (1,2) | [{…}] |
/events | where[lsn][not_in][]=1&where[lsn][not_in][]=2 | { "where": { "lsn": { "not_in": [ 1, 2 ] } } } | SELECT * FROM events WHERE lsn NOT IN (1,2) | [{…}] |
/events | where[lsn][like]=hello* | { "where": { "lsn": { "like": "hello*" } } } | SELECT * FROM events WHERE lsn LIKE 'hello*' | [{…}] |
/events | where[lsn][ilike]=hello* | { "where": { "lsn": { "ilike": "hello*" } } } | SELECT * FROM events WHERE lsn ILIKE 'hello*' | [{…}] |
/events | where[transaction][lsn]=1 | { "where": { "transaction": { "lsn": 1 } } } | SELECT * FROM events e LEFT JOIN transactions t ON e.transaction_id = t.id WHERE t.lsn = 1 | [{…}] |
Ordering
| URL Path | Query Params | JSON Request | Equivelent SQL | Response |
|---|---|---|---|---|
/events | order[id]=asc | { "order": { "id": "asc" } } | SELECT * FROM events ORDER BY id ASC | [{…}, {…}] |
/events | order[id]=asc&order[lsn]=asc | { "order": [ { "id": "asc" }, { "id": "desc" } ] } | SELECT * FROM events ORDER BY id ASC, lsn ASC | [{…}, {…}] |
/events | order[id][asc]=nulls_first | { "order": { "id": { "asc": "nulls_first" } } } | SELECT * FROM events ORDER BY id ASC NULLS FIRST | [{…}, {…}] |
/events | order[id][asc]=nulls_last | { "order": { "id": { "asc": "nulls_last" } } } | SELECT * FROM events ORDER BY id ASC NULLS LAST | [{…}, {…}] |
/events | order[id]=desc | { "order": { "id": "desc" } } | SELECT * FROM events ORDER BY id ASC | [{…}, {…}] |
/events | order[id]=desc | { "order": { "id": "desc" } } | SELECT * FROM events ORDER BY id ASC | [{…}, {…}] |
/events | order[id][desc]=nulls_first | { "order": { "id": { "desc": "nulls_first" } } } | SELECT * FROM events ORDER BY id DESC NULLS FIRST | [{…}, {…}] |
/events | order[id][desc]=nulls_last | { "order": { "id": { "desc": "nulls_last" } } } | SELECT * FROM events ORDER BY id DESC NULLS LAST | [{…}, {…}] |
Limiting
| URL Path | Query Params | JSON Request | Equivelent SQL | Response |
|---|---|---|---|---|
/events | limit=100 | { "limit": 100 } | SELECT * FROM events LIMIT 100 | [{…}, {…}] |
Including subresources
| URL Path | Query Params | JSON Request | Equivelent SQL | Response |
|---|---|---|---|---|
/events | include=transaction | { "include": "transaction" } | SELECT * FROM events e LEFT JOIN transactions t ON t.id = e.transaction_id | [{ transaction: {…}, …}, …] |
/events | include[]=transaction&include[]=database | { "include": ["transaction", "database"] } | SELECT * FROM events e LEFT JOIN transactions t ON t.id = e.transaction_id LEFT JOIN databases d ON d.id = e.database_id | [{ transaction: {…}, database: {…}, …}, …] |
/events | include[database]=account | { "include": { "transaction": "database" } } | SELECT * FROM events e LEFT JOIN databases d ON d.id = e.database_id LEFT JOIN accounts a ON a.id = d.account_id | [{ database: { account: {…}, …}, …}, …] |
Grouping
| URL Path | Query Params | JSON Request | Equivelent SQL | Response |
|---|---|---|---|---|
/events/calculate | select[count]=*&group_by=type | { "select": { "count": "*" }, "group_by": "type" } | SELECT events.type, COUNT(events.*) FROM events GROUP BY events.type | { "insert": 401, "update": 3023, …} |