Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:
curl -i "https://shape.dk/api/v1/employees?title=developer"
For POST, PATCH, and DELETE requests, parameters not included in the URL should be encoded as JSON with a Content-Type of ‘application/json’:
curl -X POST -H "Content-Type: application/json" -d '{"name":"Gert Jørgensen","title":"developer"}' https://shape.dk/api/v1/employees
Where possible our API's strives to use appropriate HTTP verbs for each action.
| Verb | Description |
|---|---|
| GET | Used for retrieving resources. |
| POST | Used for creating resources. |
| PATCH | Used for updating resources with partial JSON data. For instance, an Issue resource has title and body attributes. A PATCH request may accept one or more of the attributes to update the resource. |
| DELETE | Used for deleting resources. |
Generic responses can be encountered from any request to the API and the requester should therefore always be prepared to handle these responses.
Returns status: 401 Unauthorized
{
"status": "error",
"data": {
"message": "Unauthorized",
"error_code": "unauthorized"
}
}Returns status: 403 Forbidden
{
"status": "error",
"data": {
"message": "User doesn't have rights to create employees",
"error_code": "forbidden"
}
}Returns status: 404 Not Found
{
"status": "error",
"data": {
"message": "Not Found",
"error_code": "not_found"
}
}Returns status: 400 Bad Request
{
"status": "error",
"data": {
"message": "Not specified",
"error_code": "not_specified"
}
}Returns status: 500 Internal Server Error
{
"status": "error",
"data": {
"message": "Internal Server Error",
"error_code": "exception"
}
}All timestamps are returned in ISO 8601 format:
YYYY-MM-DDTHH:MM:SSZ
and time-only (without date):
THH:MM:SSZ
Timestamps are always saved and returned in UTC (GMT/Zulu)-time.
Images are returned as an "image" entity including a "normal" and a "retina" version:
{
"status" : "success",
"data" : {
"_id" : 1,
"name" : "Gert Jørgensen",
"title" : "Developer",
"image" : {
"normal" : "https://shape.dk/images/employees/gert.jpg",
"normal" : "https://shape.dk/images/employees/[email protected]"
}
},
"meta" : {
"url" : "https://shape.dk/api/v1/employees/1"
}
}For multiple images the response would be:
{
"status" : "success",
"data" : {
"_id" : 1,
"name" : "Gert Jørgensen",
"title" : "Developer",
"images" : [
{
"normal" : "https://shape.dk/images/employees/gert.jpg",
"normal" : "https://shape.dk/images/employees/[email protected]"
},
{
"normal" : "https://shape.dk/images/employees/gert_alternative_.jpg",
"normal" : "https://shape.dk/images/employees/[email protected]"
}
]
},
"meta" : {
"url" : "https://shape.dk/api/v1/employees/1"
}
}Returns status: 200 OK
{
"status": "success",
"data": {
"_id": 1,
"body": "This is the body.",
"created_at": "2013-12-10T15:13:22Z"
}
}Returns status: 200 OK
{
"status": "success",
"data": [
{
"_id": 1,
"body": "This is the body.",
"created_at": "2013-12-10T15:13:22Z"
},
{
"_id": 2,
"body": "This is the second body.",
"created_at": "2014-12-10T15:13:22Z"
}
]
}Pagination info is included in the meta part of the response if available.
{
"status": "success",
"data": [ ... ],
"meta": {
"current_page": 1,
"total_page_count": 4,
"page_record_count": 10,
"total_record_count": 34,
"links": {
"next": "https://shape.dk/api/v1/employees/page/2",
"prev": null,
"last": "https://shape.dk/api/v1/employees/page/4",
"first": "https://shape.dk/api/v1/employees/page/1"
}
}
}Returns status: 201 Created
{
"status": "success",
"data": {
"_id": 1,
"body": "This is the body.",
"created_at": "2013-12-10T15:13:22Z"
}
}Returns status: 400 Bad Request
{
"status": "error",
"data": {
"message": "Param not found: employee_title",
"error_code": "param_missing"
}
}Returns status: 422 Unprocessable Entity
{
"status": "error",
"data": {
"message": "Invalid",
"error_code": "invalid"
}
}The "data" element can also sometimes include an "errors" object containing the name of the model who's validation failed and an array including the specific validation errors:
{
"data": {
"error_code": "invalid",
"errors": {
"rating": [
"must be a number between 0 and 10"
]
},
"message": "Invalid"
},
"status": "error"
}TODO.
Returns status: 204 No Content
Returns status: 400 Bad Request
{
"status": "error",
"data": {
"message": "Param not found: employee_title",
"error_code": "param_missing"
}
}Returns status: 422 Unprocessable Entity
{
"status": "error",
"data": {
"message": "Invalid",
"error_code": "invalid"
}
}The "data" element can also sometimes include an "errors" object containing the name of the model who's validation failed and an array including the specific validation errors:
{
"data": {
"error_code": "invalid",
"errors": {
"rating": [
"must be a number between 0 and 10"
]
},
"message": "Invalid"
},
"status": "error"
}Returns status: 204 No Content