Authentication
The FatSecret Platform REST API allows you to access the FatSecret Platform, as long as you're signed up as a developer. To protect developers and users of the FatSecret Platform,
we use
OAuth. The REST API requires that developers use the OAuth protocol for securely signing all requests. Additional
information on
Correctly Signing your Requests with OAuth is provided below.
Note that you must be
signed up as a developer, and agree to our
Terms of Service in order to obtain you
Consumer Key and
Shared Secret, which you'll need to send requests to the
REST API. If you're using the
FatSecret Platform JavaScript API and you don't intend to
enable deep profile integration with your site, then you don't need a
Consumer Key.
There are two types of request that the REST API Supports:
Signed Requests (Consumer Key and Signature)
All requests to the to the REST API must be signed (using your pre-assigned Shared Secret).
Signed Requests, as opposed to
Signed and Delegated Requests, are where you are requesting information that is not on behalf of (or specific to) any
single user's profile with the FatSecret Platform. For instance, the
food.get API method
returns details nutritional information for a specified food. As the response of this call returns information about a shared concept (i.e.: a single food item), and there is nothing
about the response that is tailored to any specific user or individual, requests to the
food.get
API method must be signed, so that the Platform can verify the request, but the requests do not need to include the additional credentials of the particular user on whose behalf you are
making the request.
Signed and Delegated Requests (Consumer Key and Access Token and Signature)
Most requests to the REST API can be thought of as executing on behalf of an individual user. For instance,
weights.get_month
returns the recorded weight values for a nominated user and a nominated month, while
food_entry.create
records an entry in a nominated user's Food Diary.
In order to enable the recording and storage of information on a per-user basis, the FatSecret Platform provides developers with
profiles. A
profile is the unique identifier
for an individual user in the FatSecret Platform. You can create profiles for your own users on demand, by providing your own unique identifier for each profile you create (e.g.: member
name, email address, or unique member identifier) or you can create a profile without providing any user-specific information and take care of storing the profile's
oauth_token and
oauth_secret (the profile unique identifier and signing key) in your own system (see the
profile.create method).
The Profile Management REST API methods provide you with mechanisms for generating unique OAuth access tokens for each user of your site or service and for retrieving the secret for each
token so that you can sign these requests on behalf of your users. For more information see API methods:
profile.create
and
profile.get_auth.
In addition to creating
profiles for your own users, you can also use the full 3-legged OAuth provided by FatSecret.com to attain an access token for a
profile
that is directly linked to a user account on FatSecret.com. For more information click
here.
Correctly Signing Your Requests with OAuth
While you can find protocol specifications, documentation and FAQ's, at
OAuth.net please see below a summary of the main
prerequisites of the
OAuth Core 1.0 protocol used for signing FatSecret Platform REST API requests.
Note that we also provide
Client Libraries to assist you in making JavaScript/REST profile integration API calls and additional
information is available under
Resources.
Some OAuth Definitions
- User
- You (the developer)
- Consumer
- Your application
- Consumer Key
- A value we issue to you which helps us identify you
- Consumer Secret
- A secret we issue to you which helps us establish that it really is you
- Access Token
- A value which identifies a user of your application (you use the REST API Profile Management methods to generate these)
- Access Secret
- A secret we issue with the Access Token which helps us establish that you can perform a request on behalf of the user identified by the Access Token (you use the REST API Profile Management methods to generate these and/or retrieve these for your users).
Making a request
The basic steps involved in correctly signing and making requests are as follows:
Step 1. Creating a Signature Base String
You generate a Signature Base String by concatenating the HTTP method (GET or POST), the Request URL, and your query parameters in the following format:
<HTTP Method>&<Request URL>&<Normalized Parameters>
- HTTP Method
- We support both HTTP methods GET and POST.
- Request URL
-
The URL to make API calls is http://platform.fatsecret.com/rest/server.api
- Normalized Parameters
-
Please refer to the FatSecret REST API documentation for the full parameter list for each method, but for OAuth authentication the following parameters are required for every request:
- oauth_consumer_key
- Your consumer key (you can obtain one by registering here)
- oauth_signature_method
- We only support "HMAC-SHA1"
- oauth_timestamp
- The date and time, expressed in the number of seconds since January 1, 1970 00:00:00 GMT. The timestamp value must be a positive integer and must be equal or greater than the timestamp used in previous requests
- oauth_nonce
- A randomly generated string for a request that can be combined with the timestamp to produce a unique value
- oauth_version
- Must be "1.0"
-
Parameters are written in the format "name=value" and sorted using lexicographical byte value ordering, first by name and then by value. Finally
the parameters are concatenated in their sorted order into a single string, each name-value pair separated by an '&' character (ASCII code 38).
-
All request parameters (i.e. the HTTP Method, Request URL and Normalized Parameters) must be encoded using the [
RFC3986]
percent-encoding (%xx) mechanism and concatenated by an '&' character.
E.G.: A request is made using the POST HTTP method with the following parameters:
- oauth_consumer_key=demo
- oauth_signature_method=HMAC-SHA1
- oauth_timestamp=12345678
- oauth_nonce=abc
- oauth_version=1.0
- a=foo
- z=bar
The individual sections of the Signature Base String are:
- Http Method
- POST
- Request URL
- http://platform.fatsecret.com/rest/server.api is encoded to produce
http%3A%2F%2Fplatform.fatsecret.com%2Frest%2Fserver.api
- Normalized Parameters
-
First we sort the parameters:
- a=foo
- oauth_consumer_key=demo
- oauth_nonce=abc
- oauth_signature_method=HMAC-SHA1
- oauth_timestamp=12345678
- oauth_version=1.0
- z=bar
Second we concatenate the parameters:
a=foo&oauth_consumer_key=demo&oauth_nonce=abc&oauth_signature_method=HMAC-SHA1&oauth_timestamp=12345678&oauth_version=1.0&z=bar
Third we encode the sorted and concatenated string:
a%3Dfoo%26oauth_consumer_key%3Ddemo%26oauth_nonce%3Dabc%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D12345678%26oauth_version%3D1.0%26z%3Dbar
The request parameters are concatenated with the '&' to produce the Signature Base String:
POST & http%3A%2F%2Fplatform.fatsecret.com%2Frest%2Fserver.api & a%3Dfoo%26oauth_consumer_key%3Ddemo%26oauth_nonce%3Dabc%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D12345678%26oauth_version%3D1.0%26z%3Dbar
Step 2. Calculating the Signature value (oauth_signature)
Use the HMAC-SHA1 signature algorithm as defined by the [
RFC2104] to sign the request where
text is the Signature
Base String and
key is the concatenated values of the Consumer Secret and Access Secret separated by an '&' character (show '&' even if Access Secret is empty as some methods do
not require an Access Token).
The calculated digest octet string, first base64-encoded per [
RFC2045], then escaped using the
[
RFC3986] percent-encoding (%xx) mechanism is the
oauth_signature.
Step 3. Sending the Request
Send all the parameters used to generate the Signature Base String via the HTTP method specified in the Signature Base String, with the inclusion of the oauth_signature.
That's it! We will hopefully be able to generate the same oauth_signature from our end and confirm that it is indeed you.
Happy programming!