Handling Responses

SlashDB returns responses using standard HTTP status codes.

Responses to all requests will contain an appropriate HTTP status code, across all formats. In some cases, SlashDB may add HTTP headers to the response.

Info

These response codes are included in the SlashDB Logs and in Request Status entries.

Success Responses

200 OK

Any successful GET request returns a response with status code 200, with the data in the response body.

Example

Get a list of available databases:

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

HTTP/1.1 200 OK
Server: nginx/1.10.3
Date: Tue, 24 Sep 2024 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 a record from a 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 2024 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 a response with status code 201 and the URL of the new resources in the response body.

Info

For single resources, the Location header will also contain the URL.

Example

Create a new Artist record. Note the Location header:

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 2024 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

Create multiple Artist records:

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 2024 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 a request was processed successfully but there is no data to provide in the response, a 204 status is returned. This is usually encountered for PUT requests that update columns other than the 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 2024 08:01:31 GMT
Connection: keep-alive

Redirection Responses

In some cases, SlashDB may respond to a request with a 3xx status code, indicating that there is a different URL for the request, with the URL included in the Location response header. There are different redirect status codes that may be sent, depending on the context of the request.

Info

Most browsers and command line tools like curl will immediately send a request to the new URL by default.

302 Found

A 302 redirect response is returned by SlashDB for cases where:

a request is made without a limit modifier and there is a default limit set on the database
when logging out of the GUI to redirect to the home page

303 See Other

A 303 redirect response is returned by SlashDB for some requests where a JSON or XML schema has been requested and the URL can be simplified.

Example

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

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

Client Errors

Info

Error responses will always contain the error details in the Warning header, in addition to the response body.

400 Bad Request

A 400 status code is returned when a client sends a request that is considered invalid by the SlashDB application. Common causes would be sending a request with invalid URL modifier values, requesting non-existent columns from a resource or query, or trying to create a resource using invalid syntax for a given format.

Example

Trying to execute query songs-by-genre without the 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 2024 08:50:07 GMT
Content-Type: application/json
Content-Length: 147
Connection: keep-alive
Warning: Malformed URL. Missing required parameters: genre.

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

402 Payment Required

SlashDB returns status code 402 when there is a problem with the product License, such as:

license expired
invalid license key
exceeded number of users

Example

If too many users are defined in /etc/slashdb/users.cfg, the API will be locked. Requests for any user other than the 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 2024 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 a 403 status code whenever an authenticated user doesn't have sufficient privileges to the requested resource. This may occur in several contexts:

An unauthenticated user who has no access to SlashDB

For example, if the special account public is removed or disabled, then any request to SlashDB must be authenticated. An unauthenticated user can't even see a list of databases.

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

HTTP/1.1 403 Forbidden
Content-Length: 159
Content-Type: application/json
Date: Fri, 27 Sep 2024 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."}

A user without a defined login/password to a database has no access to the API

If the public user doesn't have a defined login and password to Chinook, they cannot view a 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 2024 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."}

A user without administrative privileges has no access to configuration options

For example, a user without permission to view the admin user's configuration will get a 403 response.

curl -i "http://localhost/userdef/admin.json"
HTTP/1.1 403 Forbidden
Content-Length: 159
Content-Type: application/json
Date: Fri, 27 Sep 2024 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

A 404 status code is returned when a resource cannot be found.

Example

The database Chinook does not have a 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 2024 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

Try to access a single Customer record with CustomerId = -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 2024 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

A 405 status code is returned when a resource exists but the request was sent using the incorrect HTTP method.

For example, query album-song-genre is configured to execute using the GET method; trying to run it with PUT returns an 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 2024 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

A 406 status code is returned when a request is made to a URL without a format extension and has an Accept header value that is not recognized.

Important

Recognized MIME types for the Accept header are:

text/html
application/xml, text/xml
text/xsd (deprecated)
application/json
text/csv

Learn more about how to retrieve data in a specific format.

Example

Request sent with Accept: unknown/mime header:

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

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

409 Conflict

A 409 status code is returned when a request attempts to make a change in a database which causes an integrity error.

Example

Trying to create a new resource with a primary key that already exists in the 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 2024 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

A 422 status code is returned when sending a PUT request to modify a record that causes a database integrity error.

Example

Trying to update a record's primary key to a value that identifies another 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 2024 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

A 500 status code is returned when an error was encountered during processing that was not the result of an invalid request.

Important

SlashDB Logs can be useful in diagnosing these errors. Logs are typically found in the /var/log/slashdb directory.

501 Not Implemented

If a certain feature is not currently implemented in SlashDB, a 501 status code will be returned. The feature may become available in the future.

Example

Trying to stream a response's output while also using depth to retrieve related records.

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 2024 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."}