Page tree

Client API v1

Skip to end of metadata
Go to start of metadata

This API provides endpoints that will aide in the automation and securing of data exchanged between Critical Mix and our clients. We plan to continually add new endpoints as we identify additional needs or features that could benefit both Critical Mix and our clients. While the API will continue to grow, we are committed to doing so only in a non-breaking fashion whenever possible.


How to Use our API

The production URL for this API is:

https://client-api.oneopinion.com/

We also offer a sandbox or testing URL:

https://qa-client-api.oneopinion.com/

All requests must be made over HTTPS. All data is sent and received as JSON. When making requests, you receive the response data as JSON by properly setting the Accept header to application/json. Requests which contain a body must send the data as JSON by also setting the proper Content-Type header to application/json.

Examples:

Python:

import requests
import json
    
uri = https://client-api.oneopinion.com/security/authenticate
headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
}
payload = {
    "username": "ff4e9fbe-e516-9114-1ee3-55bcaf265c79",
    "password": "...secret..."
}
response = requests.post(uri, headers=headers, json=payload)

Authentication

All endpoints provided by this API require you to provide a valid access token within a custom header, CM-Authorization. The only exception is the endpoint /security/authenticate which is used to retrieve an access token.

Critical Mix will provide you with a username and password as a part of the on-boarding process for the use of this API. The username and password are used in calls to /security/authenticate  to generate a security token. The access token will remain valid indefinitely. Access tokens are only invalidated if they are suspected to be compromised. Multiple calls to /security/authenticate will result in the same security token being returned until that token is manually invalidated.

Our recommended approach is to implement authentication for calls to any endpoint in the following manner:

  1. If your code does not have a cached authentication token, call /security/authenticate to retrieve a token
  2. Save the token in a local memory cache for re-use
  3. Call the desired endpoint using the cached security token
  4. If your request gets an authentication error (described below) then make a new call to /security/authenticate to get a new token
  5. Update your local cache with the new token
  6. Retry calling the desired endpoint with the new token

This approach minimizes the potential of your username/password becoming compromised because it is not sent with every request. The token can be invalidated and a new token easily retrieved in case of any security concerns.

Alternative approaches include:

  1. Call the /security/authenticate endpoint to get the token before every call to any other endpoint. This is acceptable, but increases the risk that your username and password become compromised.
  2. Retrieve your security token once and implement it in your code. If it becomes necessary to invalidate the token, or if you begin receiving authentication errors (described below), you would need to manually retrieve a new token and update your code.

Authentication Errors

Currently, this API does NOT return the appropriate Status codes ( 401: Unauthorized or 403: Forbidden ) for authentication and authorization errors. Instead, a 500: Internal Server Error is returned. Additionally, a JSON string which describes the error is included in the response.

{
    "timestamp": 1532615457934,
    "status": 500,
    "error": "Internal Server Error",
    "message": "Authentication failed.",
    "path": "/survey/event"
}

Requests

Requests to the various endpoints should use the appropriate specified verbs (HTTP Methods) as listed in the endpoint documentation.

If the request requires a body, the format of that body should always be well-formed JSON. The Content-Type header should be set to application\json when a JSON body is included with the request.

If an endpoint requires authentication, then the appropriate headers should be included, as detailed under Authentication.

Success Responses

HTTP Status Codes

Successful calls to the endpoints will return an appropriate HTTP Status Code from the following list: 

HTTP Status CodeUsage
200: OK

All successful calls

Success Response Headers

Header NameValueDescription
Content-Type
application/json

MIME type of the response body

Success Response Data

A response body will also be included in JSON format if one is specified for the endpoint. Check the documentation for each endpoint for details of what is included in each response.

Success Response Examples

Check the documentation for each endpoint for examples of the success response.


Error Responses

HTTP Status Codes

Calls to the endpoints which result in an error, or which are not able to successfully create or update the specified resource will return an appropriate HTTP Status Code from the following list: 

HTTP Status CodeUsage
400: Bad Request
The expected JSON body is missing or invalid, or the request is missing required parameters
404: Not Found
A non-existent resource has been requested, or data in the request body specifies a missing or invalid object.
409: ConflictA request has been made to set data in a way that conflicts with a previous request
500: Internal Server Error
Authentication error or any other error not covered by a different status code

Error Response Headers

Header NameValueDescription
Content-Type
application/json
MIME type of the response body

Error Response Data

NameTypeDescription
timestampnumberUnix timestamp of when the response was generated
statusnumberThe same value returned as the HTTP Status Code
errorstringDescription of the status code
exceptionstringDetails of the exception thrown within the API, if any.
messagestringThe user-friendly text describing the error, or "No message available"
pathstringPath of the endpoint that generated the response

Error Response Examples

HTTP/1.1 404 Not Found

{
    "timestamp": 1532627629974,
    "status": 404,
    "error": "Not Found",
    "exception": "com.criticalmix.sampleclientapi.authentication.exception.NotFoundException",
    "message": "No message available",
    "path": "/security/authenticate"
}
Write a comment…