To access the Nymbol API you need to provide authentication details via an HTTP header.
Obtaining an API key and secret ¶
In order to obtain your authentication details:
- Go to https://nymbol.co.uk/apps.
- Click the Add a new app button.
- Enter the name of your app and provide a description.
- Choose the collection(s) you want the app to be able to access.
- Click the Add app button.
Once the app is saved, you'll see the API key for the app in the list. Click the app's name, then hover over the title to see both the key and the secret (you'll need both).
Note: You should use the same app details for all versions of the app (be they iPhone, iPad or Android apps, etc).
Authenticating with the API ¶
Authentication details are passed to the API in the form of an MD5 hash.
Why MD5? ¶
As of yet, Nymbol does not support storing user-identifiable data, or allowing users to explicitly identify themselves. For this reason, we thought that to begin with, MD5 would be the simplest way of allowing authentication that didn't send any identifiable information in plain text.
Unlike using standard HTTP authentication which sends a username and password in a readily decryptable form, we combine the details into a string which can't be decrypted. The Nymbol server receives this string, then compares it with an encrypted version of your API key and secret. If the two match, authentication passes.
If you have any concerns about the security of your data, please contact us.
Creating the hash and sending it in your HTTP request ¶
You'll start off with a raw string, in the format
<key>:<secret>. Run that through your MD5 library's hashing function to produce a hex digest (a 32-digit value).
To pass this to the API, set the
Authorization HTTP header to the encrypted string.
An authenticated request to the API might look something like this:
GET /api/manager/collection.json Host: nymbol.co.uk Authorization: b4b6bfb2347932fd9cfa9642b1c1a7f7
When (and when not) to authenticate ¶
In practice, you only need to authenticate when you're calling URLs that end in
.xml. All media (images, video, etc) is available without the need for authentication. This is intended to make a developer's life easier.
If authentication fails you'll receive an HTTP response with a 403 status code.
Further reading and resources ¶
- Create MD5 Hash from NSString, NSData or a File - A guide to creating MD5 strings in iOS apps
- Create MD5 hashes in Android