GadgetKeeper provides REST API to perform functions around thing management and integration.
Authentication
GadgetKeeper allows REST clients to authenticate themselves with a user name and password using basic authentication or using API Key.
Basic HTTP authentication
Supply an "Authorization" header with content "Basic" followed by the encoded string "<USER_NAME>:<PASSWORD>"
For example, the string "fred:fred" encodes to "ZnJlZDpmcmVk" in base64, so you would make the request as follows:
API key
API Key can be sent using one of two methods as "X-ApiKey" request header or as "ApiKey" parameter in the request URL. For security reasons, sending API keys as a request header is the preferred method: while still not secure if sent over an unencrypted connection, it is less likely to be logged as part of the URL. For example you can specify your API Key "7fd0e57337ef4c88b191c7f221ed5d91" inside a header as follows:
Alternatively you can specify it as the request parameter:
HTTP Status Codes
The status code in a response indicates the state of the processing action of the request. All of the possible status codes can be grouped into five categories
|
Code Class |
Code | Description |
|---|---|---|
| Informational | 1xx | Response contains status information as the request is being processed |
| Success | 2xx | The request was valid and successfully processed |
| Redirection | 3xx | The URL of requested resource has been changed, and further action is needed |
| Client error | 4xx | There was an error in the request. Server usually includes a description of the error in its response |
| Server error | 5xx | There was an error in the server's handling of the request. Server usually returns a description of the error |
The following chart describes some of the more common codes and associated responses that are sent back from the server:
| Code Class | Code | Response | Description |
|---|---|---|---|
| Success | 200 | OK | The request has been successfully processed and a response has been returned. |
| 204 | No Content | The request has been successfully processed and there was nothing to return. | |
| Client Error | 400 | Bad Request | The server could not process the request because of invalid syntax. Errors are usually described in response body. |
| 401 | Unauthorized | User hasn't been authorized. See Authentication for details. | |
| 403 | Forbidden | User doesn't have rights to access specified resource (thing, type, etc). | |
| 404 | Not Found |
A specified resource in the request could not be found by the server (specified thing Id does not exist, specified property Id does not exist, etc.) |
|
| Server Error | 500 | Internal Server Error |
The request was valid, but the server could not process it because of an internal condition. The error is usually described in response body, but we are looking for your error experience; please notice us about it via https://github.com/GadgetKeeper/issues/issues. |
General issues with the API call (e.g. bad URL, unacceptable format, etc…) will receive one of these typical HTTP response codes. Many other codes are possible, depending on the specific nature of the call or internal state of the server. Errors are usually described in the "message" header of the response body.
Valid response examples
Typical response for a "GET" request
Typical response for a "PUT","POST", or "DELETE" request
Error response examples
Authentication required
Forbidden
Bad request
Resource is not found
Entity is not found
Internal Server Error
API explorer
Discover the GadgetKeeper API by using the API explorer.
Note: Set "Authentication" combo-box to "Basic Auth" (password-based authentication) or provide your own API Key via query or header parameters.