Skip to content

01-getting-started.md

Latest commit

 

History

History
116 lines (79 loc) · 7.26 KB

01-getting-started.md

File metadata and controls

116 lines (79 loc) · 7.26 KB

Getting Started with the Emmy API

The Emmy API is a backend data service connecting to federal and commercial data sources to help facilitate eligibility determination for state agencies. This is a REST API that uses JWT Tokens to securely send and receive JSON data.

With the Emmy API, you are able to:

  • ✅ Obtain student enrollment information
  • ✅ Verify veteran disability rating and status

Just looking for the API specs? Click here.

Technical Requirements & Prerequisites

To get started, review the requirements and prerequisites below.

Requirement Details
Obtain Credentials Contact the CMS Emmy team to get onboarded and receive your API client ID and secret. Send an email to emmy@cms.hhs.gov with the subject line "Requesting Emmy API Credentials – [state or solution provider name]" to start.
Access Emmy API Endpoints You will receive endpoints during onboarding. You must have outbound network &firewall access to this endpoint from your developer and hosting environment(s).
Make HTTP POST (REST) Calls Your system (or testing tool) must be capable of making HTTP POST calls with JSON-formatted content bodies and specific headers in the request.

Data Values Used for this Guide

During onboarding you will obtain your client credentials. The following values will be used throughout this guide and will either be provided by the onboarding team or generated by you later:

Value Source Description
client_id CMS Onboarding This is your unique client ID provided during onboarding
client_secret CMS Onboarding The secret password for your client ID
auth_base CMS Onboarding The endpoint used for authentication (but not Emmy API actions)
api_base CMS Onboarding The endpoint used for Emmy API actions (but not authentication)
base64_credentials Generated by You A Base64-encoded version of your client ID and secret
access_token Generated by You Your short-lived token used to make Emmy API calls

Throughout this guide, these parameters will be referenced and capitalized <IN_BRACKETS> to indicate where they should be used.

Using the Emmy API

To begin using the Emmy API, we will start with manual steps which ensure your credentials are valid, your connection functions, and you can construct a proper request.

Step 1: Get an Authentication Token (JWT) with your Client Credentials

To authenticate with the Emmy API, you will use your <client_id> and <client_secret> to obtain a token for all Emmy API operations. Once you obtain a token, you will use it to make all subsequent Emmy API requests. Tokens are short-lived and expire, typically after 60 minutes. You can use this token as many times as you'd like until expiration, or you can generate a new token each time.

Obtaining a token requires that you use a Basic Authentication HTTP header. This means that you will join your <client_id> and <client_secreet> with a colon : and then Base64 encode the entire string. Follow the Authentication Base64 Encoding instructions to build your credential string. We'll refer to the credential string that you generate as <base64_credentials>.

For simplicity, we'll use curl to showcase getting an access token. From a terminal or command prompt, run this curl command (how do I install curl?) by substituting the appropriate variables (shown <IN_BRACKETS> below) with their actual values:

curl --location '<AUTH_BASE>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--user '<CLIENT_ID>:<CLIENT_SECRET>' \
--data-urlencode 'grant_type=client_credentials'

After successfully running this command, a JSON response which contains your freshly minted <access_token> will appear. Here is an example (note that your response will likely not be beautifully indented):

{
    "access_token": "<ACCESS_TOKEN>",
    "expires_in": 3600,
    "token_type": "Bearer"
}

Copy the access_token value from the response. Now you are ready to prepare your request payload and call an Emmy API endpoint.

(Review the Authentication Guide for more details on authenticating. Also consider browsing the Postman Examples or curl Examples for more help using these tools.)

Step 2: Prepare your Request Payload

Requests to the Emmy API use JSON content payloads in the request body. First, review the Emmy API specification for the operation you would like to perform. In this example, we will make request a member's educational enrollment information from the Emmy API's /v0/education-enrollments endpoint.

In the API specs for /v0/education-enrollments, you can see the structure of the request body. Build a JSON body using your member's information, like so:

{
  "firstName": "Lynette",
  "lastName": "Oyola",
  "dateOfBirth": "1988-10-24"
}

With your JSON payload prepared, you can now make a request to the Emmy API.

Step 3: Invoke an Emmy API Request

In this step, we will again use the curl tool to make a request to the Emmy API. We will continue the example from step 2 and request member information from the Education /v0/education-enrollments endpoint.

This request is slightly more complex since it now has HTTP authorization, a content body, and a different endpoint. Use this example by substituting the values for your environment:

curl --location --request POST '<API_BASE>/v0/education-enrollments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--data '{
  "firstName": "Lynette",
  "lastName": "Oyola",
  "dateOfBirth": "1988-10-24"
}'

After a moment, the Emmy API will provide a verification response for the applicant identifying information you provided.

(Note that if you are testing an endpoint which might have a self-signed certificate, you can use the -k option on the curl command to accept the certificate and proceed.)

Next Steps

Now that you have completed an end-to-end test of using the Emmy API, you can use these lessons learned to connect to and use the API in your own application.