Skip to end of metadata
Go to start of metadata

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

CodeDescription
Informational1xxResponse contains status information as the request is being processed
Success2xxThe request was valid and successfully processed
Redirection3xxThe URL of requested resource has been changed, and further action is needed
Client error4xxThere was an error in the request. Server usually includes a description of the error in its response
Server error5xxThere 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 ClassCodeResponseDescription
Success       200OKThe request has been successfully processed and a response has been returned.
204No ContentThe request has been successfully processed and there was nothing to return.
Client Error400Bad RequestThe server could not process the request because of invalid syntax. Errors are usually described in response body.
401UnauthorizedUser hasn't been authorized. See Authentication for details.
403ForbiddenUser doesn't have rights to access specified resource (thing, type, etc).
404Not 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 Error500Internal 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.

  • No labels