Skip to content

Handling Responses

SlashDB returns responses preserving standard HTTP Status Code classification. Resource data as well as error messages that are returned in response body are in requested format (CSV, JSON, XML, XSD, HTML). You can find out more here, how to define the response format type.

Success Responses

200 OK

Any successfully processed GET request returns response with status code 200 and proper data in body.

Example:

Get list of available APIs.

curl -i "http://localhost/db.json"

HTTP/1.1 200 OK
Server: nginx/1.10.3
Date: Tue, 24 Sep 2019 08:48:46 GMT
Content-Type: application/json
Content-Length: 187
Connection: keep-alive

[
    {
        "db_id": "Chinook",
        "__href": "/db/Chinook.json",
        "type": "sqlite",
        "description": "Example SQLite database",
        "status": "Connected"
    }
]

Get data from database

curl -i "http://localhost/db/Chinook/Customer/CustomerId/1/FirstName,LastName,Email.json"

HTTP/1.1 200 OK
Server: nginx/1.10.3
Date: Wed, 25 Sep 2019 06:57:28 GMT
Content-Type: application/json
Content-Length: 103
Connection: keep-alive

{
    "FirstName": "Lu\u00eds",
    "LastName": "Gon\u00e7alves",
    "Email": "luisg@embraer.com.br"
}

201 Created

A POST request that creates new resources returns response with status code 201 and location of new resources.

Example:

HTTP status code 201 confirms that a new record was added to table Artist in database Chinook. Header Location has a full URL to new resource and body has URL paths to them. 

curl -i -X POST "http://localhost/db/Chinook/Artist.json" -d '{"Name": "New Artist"}'

HTTP/1.1 201 Created
Server: nginx/1.10.3
Date: Wed, 25 Sep 2019 07:07:00 GMT
Content-Type: text/html; charset=utf-8
Content-Length: 31
Connection: keep-alive
Location: http://192.168.1.73/db/Chinook/Artist/ArtistId/276.json

/db/Chinook/Artist/ArtistId/276

Example:

Just like above but multiple resources are created. In that case there's no Location header but multiple URL paths are present in body.

curl -i -X POST "http://localhost/db/Chinook/Artist.json" \
-d '[{"Name": "New Artist 1"}, {"Name": "New Artist 2"}]'

HTTP/1.1 201 Created
Server: nginx/1.10.3
Date: Wed, 25 Sep 2019 07:14:52 GMT
Content-Type: text/html; charset=utf-8
Content-Length: 63
Connection: keep-alive

/db/Chinook/Artist/ArtistId/277
/db/Chinook/Artist/ArtistId/278

204 No Content

When request was processed successfully but not returning any body to the client then response with status code 204 is returned. Most typical case is for PUT request that modifies columns other than primary key.

Example:

curl -i -X PUT "http://localhost/db/Chinook/Artist/ArtistId/277.json" \
-d '{"Name": "Changed Arist 1"}'

HTTP/1.1 204 No Content
Server: nginx/1.10.3
Date: Wed, 25 Sep 2019 08:01:31 GMT
Connection: keep-alive

Redirection Responses

302 Found

SlashDB tells the client to look at (browse to) another URL in case:

  • request is made without limit and limit is set on database
  • on logout in GUI to redirect user to main page

303 See Other

Response tells client to look for resource under different URL. In SlashDB it's used when XSD address can be simplified.

Example:

curl -I http://localhost/db/Chinook/Customer/Country/USA/State/CA/Invoice.xsd

HTTP/1.1 303 See Other
Server: nginx/1.12.2
Date: Fri, 27 Sep 2019 10:21:09 GMT
Content-Type: text/html; charset=UTF-8
Content-Length: 228
Connection: keep-alive
Location: http://localhost/db/Chinook/Invoice.xsd

Client Errors

400 Bad Request

Most general response for client error. Response 400 Bad Request is returned when request cannot be processed because it was constructed incorrectly. In that case the response contains explanation in header Warning and body.

Example:

Trying to execute SQL Pass-Thru query songs-by-genre without required parameter genre.

curl -i "http://192.168.1.73/query/songs-by-genre.json"

HTTP/1.1 400 Bad Request
Server: nginx/1.10.3
Date: Wed, 25 Sep 2019 08:50:07 GMT
Content-Type: application/json
Content-Length: 147
Connection: keep-alive
Warning: Malformed URL. Missing required parameters: genre.

{"url_template": "/query/songs-by-genre/genre/{genre}.json", "http_code": 400, "description": "Malformed URL. Missing required parameters: genre."}

402 Payment Required

SlashDB returns status code 402 when there's problem with license like:

  • license expired,
  • invalid license key,
  • exceeded number of users

Example:

Too many users were defined in /etc/slashdb/users.cfg. When SlashDB is started the API will be locked. Requests for any user other than admin return HTTP 402. 

curl -i "http://localhost/db/Chinook.json"

HTTP/1.1 402 Payment Required
Content-Length: 88
Content-Type: application/json
Date: Fri, 27 Sep 2019 10:38:55 GMT
Server: waitress
Warning: License verification unsuccessful - too many users.

{"http_code": 402, "description": "License verification unsuccessful - too many users."}

403 Forbidden

SlashDB returns 403 Forbidden whenever authenticated user doesn't have sufficient privileges to the requested resource. This may occur on several levels:

Unauthenticated user has access to SlashDB

For example when special account public is removed then any request to SlashDB must be authenticated. Unauthenticated user can't even see list of APIs.

curl -i "http://localhost/db.json"

HTTP/1.1 403 Forbidden
Content-Length: 159
Content-Type: application/json
Date: Fri, 27 Sep 2019 10:53:20 GMT
Server: waitress
Warning: Access was denied to this resource. Please log in with your username/password or resend your request with a valid API key.

{"http_code": 403, "description": "Access was denied to this resource. Please log in with your username/password or resend your request with a valid API key."}
User without defined login/password to database has no access to certain API

For example user public which doesn't have defined login and password to database Chinook cannot view list of tables in that database.

curl -i "http://localhost/db/Chinook.json"

HTTP/1.1 403 Forbidden
Content-Length: 159
Content-Type: application/json
Date: Fri, 27 Sep 2019 10:55:31 GMT
Server: waitress
Warning: Access was denied to this resource. Please log in with your username/password or resend your request with a valid API key.

{"http_code": 403, "description": "Access was denied to this resource. Please log in with your username/password or resend your request with a valid API key."}
User without administrative privileges has no access to configuration of SlashDB

For example user without permission to view admin's configuration get 403 Forbidden response.

curl -i "http://localhost/userdef/admin.json"
HTTP/1.1 403 Forbidden
Content-Length: 159
Content-Type: application/json
Date: Fri, 27 Sep 2019 10:56:01 GMT
Server: waitress
Warning: Access was denied to this resource. Please log in with your username/password or resend your request with a valid API key.

{"http_code": 403, "description": "Access was denied to this resource. Please log in with your username/password or resend your request with a valid API key."}

404 Not Found

Returned when resource was not found. Typical reason would be misspelled URL or missing resource if searched by primary key.

Example:

The database Chinook does not have table named NoSuchTable.

curl -i -X GET "http://192.168.1.73/db/Chinook/NoSuchTable.json"

HTTP/1.1 404 Not Found
Server: nginx/1.10.3
Date: Mon, 23 Sep 2019 13:51:03 GMT
Content-Type: application/json
Content-Length: 69
Connection: keep-alive
Warning: The resource could not be found.

{"http_code": 404, "description": "The resource could not be found."}

Example:

Filtered on primary key and there's no record for CustomerId equal -1. 

curl -i -H "apikey: admin1234" "http://192.168.1.73/db/Chinook/Customer/CustomerId/-1.json"

HTTP/1.1 404 Not Found
Server: nginx/1.10.3
Date: Tue, 24 Sep 2019 08:54:46 GMT
Content-Type: application/json
Content-Length: 69
Connection: keep-alive
Warning: The resource could not be found.

{"http_code": 404, "description": "The resource could not be found."}

405 Method Not Allowed

Returned when resource exists but request has incorrect HTTP method. More detailed explanation can be found in response body or header Warning.

For example below album-song-genre query was defined to be executed on GET request hence using PUT method returned error.

curl -i -X PUT "http://localhost/query/album-song-genre.json?apikey=admin1234"

HTTP/1.1 405 Method Not Allowed
Server: nginx/1.10.3
Date: Mon, 23 Sep 2019 13:37:41 GMT
Content-Type: application/json
Content-Length: 172
Connection: keep-alive
Warning: This method is not allowed for query: "album-song-genre". Allowed methods: ["GET"].

{"url_template": "/query/album-song-genre.json", "http_code": 405, "description": "This method is not allowed for query: \"album-song-genre\". Allowed methods: [\"GET\"]."}

406 Not Acceptable

When a request is made to a URL without an extension and with an Accept header value that is not recognized, then the server returns a 406 Not Acceptable response to indicate that the format for the response data has not been specified (e.g. XML, XSD, JSON, CSV, HTML).

Recognized MIME types for the Accept header are:

  • text/html
  • application/xml, text/xml
  • text/xsd
  • application/json
  • text/csv

You can find more here about how to make a request to retrieve output in a specific format.

Example:

Request with Accept: unkonwn/mime 

curl -i "http://localhost:/db/Chinook/Customer" \
-H "Accept: unknown/mime"

HTTP/1.1 406 Not Acceptable
Content-Length: 0
Date: Fri, 27 Sep 2019 13:28:33 GMT
Server: waitress
Warning: Unsupported format 'unknown/mime' for this resource.

409 Conflict

SlashDB return response 409 Conflict whenever a request tries to make a change in a database which causes an integrity error. Header Warning and body contain error message returned by the database.

Typical case is when trying to incorrectly modify primary key or foreign key.

Example:

Trying to create a new resource with primary key that already exists in table.

curl -i -X POST "http://localhost/db/Chinook/Artist.json" \
-d '{"ArtistId": 1, "Name": "New Artist"}'

HTTP/1.1 409 Conflict
Content-Length: 128
Content-Type: application/json
Date: Fri, 27 Sep 2019 13:44:09 GMT
Server: waitress
Warning: Database Integrity Error (sqlite3.IntegrityError) UNIQUE constraint failed: Artist.ArtistId

{"http_code": 409, "description": "Database Integrity Error (sqlite3.IntegrityError) UNIQUE constraint failed: Artist.ArtistId"}

422 Unprocessable Entity

When integrity error occurs on database when making PUT request then HTTP 422 Unprocessable Enttity is returned.

Example:

Updating primary key with value that identifies other record.

curl -i -X PUT "http://localhost/db/Chinook/Customer/CustomerId/1.json" -d '{"CustomerId": 2}'

HTTP/1.1 422 Unprocessable Entity
Content-Length: 148
Content-Type: application/json
Date: Mon, 30 Sep 2019 08:48:49 GMT
Server: waitress
Warning: Commit to database failed during update. (sqlite3.IntegrityError) UNIQUE constraint failed: Customer.CustomerId

{"http_code": 422, "description": "Commit to database failed during update. (sqlite3.IntegrityError) UNIQUE constraint failed: Customer.CustomerId"}

Server Errors

500 Internal Server Error

In general status code 500 is returned whenever request is correct but processing it fails unexpectedly. In such situations log files in /var/log/slashdb contain more information useful for debugging the cause.

501 Not Implemented

When certain functionality is not implemented yet then SlashDB will return 501 Not Implemented. The feature may become available in the future.

Example:

Streaming result objects with related objects when query string parameter depth is greater than 0.

curl -i "http://localhost/db/Chinook/Customer/CustomerId/1.json?depth=1&stream=true"

HTTP/1.1 501 Not Implemented
Content-Length: 95
Content-Type: application/json
Date: Mon, 30 Sep 2019 12:53:00 GMT
Server: waitress
Warning: Streaming nested objects from database is not implemented.

{"http_code": 501, "description": "Streaming nested objects from database is not implemented."}