Get Started

The HelloFlex APIs are HTTP-based RESTful APIs that use OAuth 2.0 for authorization. API request and response bodies are formatted in JSON.

Important: You cannot run the sample requests in this guide as-is. Replace call-specific parameters such as tokens and IDs with your own values.

Authentication and authorization

The HelloFlex REST API uses the OAuth 2.0 protocol to authorize calls. OAuth is an open standard that many companies use to provide secure access to protected resources.

When you create an app, HelloFlex generates a set of OAuth client ID and secret credentials for your app for requested environment. For more details please check to API User management documentation. You pass these credentials in the Authorization header in a get access token request.

In exchange for these credentials, the HelloFlex authorization server issues access tokens called bearer tokens that you use for authorization when you make REST API requests. A bearer token enables you to complete actions on behalf of, and with the approval of, the resource owner.

The access_token field in the get access token response contains a bearer token, indicated by the token_type of Bearer:

{
	"access_token": "<Access-Token>",
	"token_type": "Bearer",
	"expires_in": 3599
}

Include this bearer token in API requests in the Authorization header with the Bearer authentication scheme.

This sample request uses a bearer token to list news for a customer:

curl -X GET \
	-H 'Accept: application/json' \
	-H 'Authorization: Bearer <Access-Token>' \
	'https://api.uat-helloflex.com/api/publicnews'

Access tokens have a finite lifetime. The expires_in field in the get access token response indicates the lifetime, in seconds, of the access token. For example, an expiry value of 3600 indicates that the access token expires in one hour from the time the response was generated.

To detect when an access token expires, write code to either:

• Keep track of the expires_in value in the token response. The value is expressed in seconds.
• Handle the HTTP 401 Unauthorized status code. The API endpoint issues this status code when it detects an expired token.

Before you create another token, re-use the access token until it expires.

API requests

To construct a REST API request, combine these components:

API responses

HelloFlex API calls return JSON response bodies that include information about the resource.

HTTP status codes

Each REST API request returns a success or error HTTP status code.

Success

In the responses, HelloFlex returns these HTTP status codes for successful requests:

Error

In the responses for failed requests, HelloFlex returns HTTP 4XX or 5XX status codes.

In the responses, HelloFlex returns these HTTP status codes for failed requests:

Validation errors

For validation errors, HelloFlex returns the HTTP 400 Bad Request status code.

Sample of validation response:

{
	"Id": ["Value -1 is invalid."],
	"Lang": ["Should be valid ISO 639-1 language code."]
}

Make your first call

To make REST API calls, you need to get an access token.

Get an access token

The get access token endpoint is /oauth2/token.

To get an access token, you pass your OAuth credentials in a get access token call. To make this call, you can use either cURL on the command line or the Postman app.

In response, the HelloFlex authorization server issues an access token.

Re-use the access token until it expires. When it expires, you can get a new token.

cURL example

Tips:

• If you use Windows, use a Bash shell to make cURL calls.
• If you use a command-line tool other than cURL, set content-type to application/x-www-form-urlencoded.

1. Download cURL for your environment.

2. From the command line, run this command:

   curl -X POST \
   	-H "Accept: application/json" \
   	-d "client_id=<client_id>" \
   	-d "client_secret=<secret>" \
   	-d "grant_type=client_credentials" \
   	<token endpoint>

   Where:

   <token endpoint>	The get access token endpoint.
   <client_id>	Your client ID.
   <secret>	Your secret.
   grant_type	The grant type. Set to client_credentials.

3. View the sample response.

Postman example

1. Download the latest version of Postman for your environment, and open Postman.

2. Select the POST method.

3. Enter the https://api.uat-helloflex.com/oauth2/token request URL.

4. On the Body tab, select x-www-form-urlencoded and enter this information:

   Key	Value
   grant_type	client_credentials
   client_id	Your client ID.
   client_secret	Your secret.

5. Click Send.

6. View the sample response.

Sample response

{
	"access_token": "<Access-Token>",
	"token_type": "Bearer",
	"expires_in": 3599
}

Where:

Make REST API calls

With a valid access token, you can make REST API calls.

Add Authorization request header with value "Bearer <Access-Token>" where <Access-Token> is your access token.

This sample call returns public news and uses only the required input parameters. The access token in the call is an OAuth bearer token.

curl -X GET \
	-H 'Accept: application/json' \
	-H 'Authorization: Bearer <Access-Token>' \
	'https://api.uat-helloflex.com/api/publicnews'

A successful call returns a JSON-formatted response body with public news.