Introduction
Welcome to the SWCE API.
The API is a (mostly) RESTful service, with authentication handled by API tokens sent as a header or parameter on every request.
You can send us pull request for any changes you think should be made to these docs over on Github
API Endpoint
The API endpoint is:
https://api.swcollectionsexplorer.org.uk/api/v1/
Formats
By default, the API returns everything in JSON. We recommend you consume this, and provide an Accept: application/json
header with each call, although you will receive json without it.
XML is also available on every request if you prefer it, just send us an Accept: application/xml
header.
Rate Limiting
You can make 60 requests to the API every 60 seconds.
After this, you’ll receive an 429 Too Many Requests
status.
You can check your rate limit status by reading the X-RateLimit-Limit
and X-RateLimit-Remaining
headers returned on every request.
Authentication
SWCE currently only offers API tokens to allow access to the API. You can register a new API token key at our developer portal.
SWCE requires the API key to be included in all API requests to the server in a header that looks like the following:
Authorization: Bearer w0WlRHfwbbr4JUJygL
Alternatively, you can make any request and append an api_token parameter:
https://api.swcollectionsexplorer.org.uk/api/v1/sites?api_token=w0WlRHfwbbr4JUJygL
We recommend using the bearer token approach.
Objects
Get All Objects
curl -X "GET" "https://api.swcollectionsexplorer.org.uk/api/v1/objects" \
-H "Authorization: Bearer w0WlRHfwbbr4JUJygL"
The above command returns JSON structured like this:
{
"total": 11379,
"per_page": 50,
"current_page": 1,
"last_page": 228,
"next_page_url": "https://api.swcollectionsexplorer.org.uk/api/v1/objects?page=2",
"prev_page_url": null,
"from": 1,
"to": 50,
"data": [
{
"id": 1,
"accession-loan-no": "71/1929",
"simple-name": "door",
"full-name": null,
"collector-excavator": null,
"collection-country": "England",
...
"site": {
"name": "RAMM"
},
"category": {
"name": "Antiquities",
"slug": "antiquities"
}
},
...
]
}
This endpoint retrieves all objects.
HTTP Request
GET objects
Query Parameters
Parameter | Default | Description |
---|---|---|
site | null | Limit results to only one site ID |
since | null | Only return objects modified since this timestamp (2016-04-10 18:00:00 format) |
category | null | Limit results to this category slug |
per_page | 50 | The number of results per page (min 10, max 250) |
Get a Specific Object
curl -X "GET" "https://api.swcollectionsexplorer.org.uk/api/v1/object/1" \
-H "Authorization: Bearer w0WlRHfwbbr4JUJygL"
The above command returns JSON structured like this:
{
"id": 1,
"accession-loan-no": "160/1999",
"simple-name": "architectural fragment",
"full-name": "label stop",
"collector-excavator": "Pearce, Nan, Mrs",
"collection-country": "England",
"description": "This architectural fragment is shaped as a queenâs head with curly hair. It was salvaged from a demolished house in Membury, Devon, where it had been used in a 20th century fireplace. It was probably once part of the local church.",
"mint": null,
"medium": null,
"geology-period": null,
"common-name": "label stop",
"family": null,
...
"site": {
"name": "RAMM"
},
"category": {
"name": "Antiquities",
"slug": "antiquities"
}
}
This endpoint retrieves a specific object.
HTTP Request
GET object/<ID>
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the object to retrieve |
Errors
The SWCE API uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request – Your request is invalid |
401 | Unauthorized – Your API key is not valid |
403 | Forbidden – The endpoint requested is hidden for administrators only |
404 | Not Found – The specified item could not be found |
405 | Method Not Allowed – You tried to access a item with an invalid method |
406 | Not Acceptable – You requested a format that isn’t json or xml |
429 | Too Many Requests – You have been rate limited. |
500 | Internal Server Error – We had a problem with our server. Try again later. |
503 | Service Unavailable – We’re temporarily offline for maintenance. Please try again later. |