Endpoint Discovery

Nutshell offers a specialized API at api.nutshell.com which your application must use to find the API endpoint for each user. This API, like the full Nutshell API, has both JSON-RPC and SOAP endpoints.

• JSON-RPC endpoint: http://api.nutshell.com/v1/json
• SOAP endpoint: http://api.nutshell.com/v1/soap

This API has one method, getApiForUsername. It accepts one parameter, username: the user that wishes to log in.

The API will respond with an array of domains which the user can login to.

This example output is shown in JSON format, but the API is available via both JSON-RPC and SOAP.

"result": {
   "iphone": "app01.nutshell.com", 
   "api": "app01.nutshell.com", 
   "login": "app01.nutshell.com"
}

Your application should cache this response for the next 10 - 90 minutes.

Building the Endpoint URL

Once your application has the domain name the user should login to, building the rest of the endpoint URL is simple.

The domain should be prefixed with https:// (the Nutshell API requires HTTPS). After the domain name comes the API version, in the format api/vX. api/v1 is currently the only valid version of the Nutshell API. Finally, either /json or /soap should be appended to the URL, depending on the protocol your application wishes to use.

Continuing from the example given above, one might end up with the API endpoint URL https://app01.nutshell.com/api/v1/json.