Pearson
Always Learning

Overview

This use case describes the step-by-step process for you to build and submit an API request using the OAuth 1.0a protocol.

Note: We recommend that you build the collection of the required parameters with values before beginning to build the signature itself. That way, you can extract each parameter/value pair as needed while building the signature base string and X-Authorization request header.

 

Libraries & Sample Code

Reading the documentation is wise to better understand how to create a signature and use it in a request. To make it easier, we have the LearningStudio Libraries that can generate a signature for a request, and even fire the request handling authentication behind the scenes. If you want to roll your own code, check out the OAuth 1 sample code for working examples.


URL Components

You will be manipulating separate parts of your complete API request to create the signature base string and X-Authorization header used during OAuth 1.0a authentication. Following are definitions of the terms that we will use to identify these components.

Structure of a typical API request:

verb https://domain/route?queryStringParameter requestHeader { requestBody }

Sample URL request used in the Example column:

GET https://api.learningstudio.com/users/123456/courses/upcomingevents?since=03/01/2013&until=12/31/2013

TermDefinitionExample
verbOne of the RESTful verbs: GET, POST, PUT, or DELETE.GET
domainAPI hostname.api.learningstudio.com
routeThe relative URI with route parameters. Does not include the verb, domain, or any query strings./users/123456/upcomingevents
queryStringOne or more query strings used to modify the request. See Query Strings for more information.?since=03/01/2013&until=12/31/2013
requestHeaderHeader information for the API request. It must contain the X-Authorization request header with the signature authorization information for the request. 
requestBodyRequest body or "data payload" of the URL request. 
urlFull URL for the API request, including verb, domain, route, and query strings. Do not include the request header or the request body.GET https://api.learningstudio.com/users/123456/upcomingevents?since=03/01/2013&until=12/31/2013
domainRouteDomain and route for the API request, but without the verb or any query strings.https://api.learningstudio.com/users/123456/upcomingevents

Build and Submit Sequence

Click each link to open the referenced content to get detailed information.

 

StepNotes

1. Build the API request being made and save in your collection. You will be using the different components of it in the following steps.

  a. Include all route parameters and any query strings.

  b. If your API request verb is POST or PUT, include the request body.

 

2. If the API request has a request body, encode the request body as follows; otherwise, skip this step.

  a. Base-64 encode the request body.

  b. URL-encode the result.

  c. URL-encode the result again.

  d. Save this value in your collection. It will be used in the body= parameter.

 

3. Create and save the following parameter/value combinations in your collection. Do not encode the values.

 

  • application_Id={applicationId}
  • oauth_consumer_key={consumerKey}
  • oauth_nonce={nonceValue}
  • oauth_signature_method=CMAC-AES
  • oauth_timestamp={timestamp}
  • body={requestBody} - Include only if you created the encoded request body in step 2. If your API request does not have a request body, exclude the entire parameter (do not define as a "null" value because this will cause your request to fail).
  • {querystring}={querystringparameter} - Repeat for each query string being used in the API request.

 

See Signature Base String Parameters for descriptions of each parameter.

4. In alphabetical order based on the parameter name, extract each parameter/value pair and place it in a string, using an ampersand to separate each pair. If your API request includes query strings, be sure to include each {querystring}={querystringparameter} pair in the appropropriate alphabetical order.

Example: application_Id={applicationId}&body={requestBody}&oauth_consumer_key={consumerKey}&oauth_nonce={nonceValue}&oauth_signature_method={hashMethod}&oauth_timestamp={timestamp}

 

5. URL-encode the entire string that is the result of step 4.

Example: application_Id%3D{applicationId}%26body%3D{requestBody}%26oauth_consumer_key%3D{consumerKey}%26oauth_nonce%3D{nonceValue}%26oauth_signature_method%3D{hashMethod}%26oauth_timestamp%3D{timestamp}

 

6. Extract the route value from your API request and URL-encode it.

Example: /users/654321/courses becomes %2Fusers%2F654321%2Fcourses%2F123456

 

7. To the beginning of string, add the verb followed by an ampersand ( & ), then the encoded route from step 6 followed by an ampersand ( & ).

Example: {verb}&{encodedRoute}&application_Id%3D{applicationId}%26body%3D{requestBody}%26oauth_consumer_key%3D{consumerKey}%26oauth_nonce%3D{nonceValue}%26oauth_signature_method%3D{hashMethod}%26oauth_timestamp%3D{timestamp}

See Signature Base String Syntax for a description of the syntax.

8. Create the signature hash.

  a. Encrypt the string created in step 7 using the CMAC-AES process. Use your consumer secret as the CMAC key.

  b. Base-64 encode the encryted value.

  c. Save in your collection.

 

9. Build the X-Authorization header by extracting the following parameter/value pairs from your collection to add to the header string. After the realm= parameter, separate the parameter/value pairs with commas. Do not encode the values. Do not include any query strings.

 

  • X-Authorization OAuth
  • realm="{domainRoute}"
  • application_Id="{applicationId}"
  • oauth_consumer_key="{consumerKey}"
  • oauth_nonce="{nonceValue}"
  • oauth_signature_method="CMAC-AES"
  • oauth_timestamp="{timestamp}"

 

Example: X-Authorization: OAuth realm="{domainRoute}",application_id="{applicationId}",oauth_consumerkey="{consumerKey}",oauth_nonce="{nonceValue}",oauth_signature_method="{hashMethod}",oauth-timestamp="{timestamp}",oauth_signature="{signatureValue}"

See X-Authorization Syntax for descriptions of each parameter.

10. Add the X-Authorization header to your API request and submit it.

 

The use case for Submit API Request Using OAuth 1.0a is finished.

 

 

4618 reads
Always Learning
Pearson