Introduction

Epixel MLM Commission Engine API Integration

Purpose

This document aims to describe how external client applications can integrate with the Epixel MLM software API system.

What is an API?

API is the acronym for the term Application Programming Interface. API defines how an application implements the interface for external applications to communicate with it and use it’s functionalities exposed to the outside world. It specifies the technical language to be used for this communication.

The client application “calls” an API implemented by a system to fetch a resource it’s looking for or get some action done. This is known as a “request” to which the host system responds by sending back a “response”, which could be a representation of a resource or the acknowledgement of an action taken. The responses are usually sent back in JSON(Javascript Object Notation) format.

A client application can be of any of the following types -

Web Server App - An app’s backend server calls the API,

Mobile App - End-user’s mobile device directly calls the API.

Single-page App - A web-browser based app calls the API(eg. React/Angular app)

API Basics

The Epixel MLM software implements an API over the HTTP protocol. This means that the clients must communicate with it via standard http calls like GET, POST, PUT and DELETE etc.

An HTTP API request usually has the following format -

METHOD https://www.api.hostname/endpoint?parm1=value1&parm2=value2

This request consists of the following parts -

Method - This specifies the action to be taken. HEAD, GET, POST, PUT, DELETE are some of the common HTTP methods used in API calls.

Commonly used HTTP methods -

GET - Used to fetch data from the server. Should not affect the data.

HEAD - Same as GET, but transfers the status line and header section only. Used to check the availability of a resource.

POST - Used to send data to the server, such as file upload or for submitting user information through forms

PUT - Replaces the current representations of the target resource with the uploaded content.

DELETE - Removes all current representations of the target resource given by a URI.

Endpoint - The endpoint usually represents a resource (eg.- the profile page of a user) or some action (eg.- logging in a user) at the host system. It consists of the hostname part followed by the endpoint identifier. The endpoints of an API represent the resources of the system exposed to the outside world and also the various actions that one can make on those resources. An endpoint is also called a URL (Universal Resource Locator) or URI (Universal Resource Identifier).

Query parameters - These are the additional arguments that are required to be passed along with the endpoint name. Eg - The username name of a user.

Following would be a simple example of an API call in the format discussed above -

GET https://epixelmlmsystem/profile?user=david

This call gets the profile details of the user david from https://epixelmlmsystem through the endpoint profile. (This assumes that the user has already been authenticated in the system)

Integrating Client Applications with Epixel MLM API System.

For external client applications to use the Epixel MLM API system, they have to be integrated with it first.

This process starts with the MLM system admin registering the external application in its API system. On registering the application the system generates an application token which will be JSON(Javascript Object Notation) encoded as a Base64URL string.

The client application must furnish the following details during the app registraton -

  • Project/Application name

  • Client type - Mobile, Web backend or Browser-based application.

The registration step will generate the app token with the following details encoded -

{

typ: Application type - server, web or mobile

aud: audience - the application id

iss: authentication server identifier

iat: issued-at timestamp

}

A token in this format is known as JSON Web Token (JWT). These key - value pairs are known as claims of the token.

Client authentication for public access

When there is no user-login involved, the authentication flow will be as follows -

All the API requests from the application is supposed to carry the application token to be considered valid in the MLM API system. The information presented by the token claims will be validated by the API server during the authentication of the API requests.

Any request that doesn't carry the application token will be rejected by the API as having inadequate permission. So the client application must store this token securely in its database and include it in all the API requests that it makes to the MLM API. The token represents the client's identity to the API and hence must not be shared with any third party.

The following example depitcs a sample API request using CURL (Command URL) utility.

This API request is trying to register a user at the /api/register endpoint. The user details are passed as input in JSON format. The application token is included in the header as "Application-Token: {app token value}"

Client authentication for logged-in user

The authentication flow for client API requests involving a user who needs extra authentication is different from the flow for public access described in the previous section. In addition to the application token the requests need to carry an access token for the user. To obtain the access token the user needs to login providing his/her login credentials to the API server.

Sample request to the /token endpoint -

Sample response with access and refresh tokens in JSON -

The response contains a refresh token in addition to the access token. This is to be used whenever an access token expires. Presenting the refresh token at the /token endpoint will give the client a new access token.

Once the client get the access token for a user, every API request on behalf of that user is supposed to carry the access token. The MLM API expects this access token to be sent in a cookie.

A sampe request passing the access token -

The request above tries to fetch the profile of the user "johnsamuels". The access token obtained in the previous step is passed as a cookie named access_token.

Once the access token gets expired, the client requests the /token endpoint of the API for a new access token, sending the refresh token as input.

Sample API request for requesting a new access token -

HTTP Standard status codes

Error Code

Description

1xx: Informational

Communicates transfer protocol-level information.

200

OK, Successful

201

Created, Resource creation is successful.

204

No Content

400

Bad Request, Bad input parameter. Error messages should indicate which one and why.

401

Unauthorized, The client passed in the invalid Auth token. The client should refresh the token and then try again.

403

Forbidden, Authentication failed due to invalid authentication permissions.

404

Not Found, Resource not found.

405

Method Not Allowed, The resource doesn't support the specified HTTP verb.

409

Conflict. The request could not be completed due to a conflict with the current state of the target resource.

500

Internal Server Error, Servers are not working as expected. The request is probably valid but needs to be requested again later.

503

Service Unavailable.

Error Response Structure

Basic error structure

{
"status_code": <HTTP response status code>,
"errors": {
"type": "<Error name>",
"detail": [
{
"message": "<Detailed error description>"
}
]
}
}

Validation error structure

{
"status_code": 400,
"errors": {
"type": "Validation Error",
"detail": [
{
"attribute": "<Field Name>",
"message": <Array of messages>
}
]
}
}

Paramater

Data Type

Description

status_code

Int

Http reponse status code

Example : 500,403,400

type

String

Short name for the error.

message

Sting

Long description about the error.

Example:

"detail": [ { "message": "Something went wrong. Couldn't process the request.} ]

Common Error Responses

Status Code

Error Type

Description

500

Server Error

Something went wrong. Couldn't process the request.

401

Request Failed

Something went wrong couldn't validate request through APIKEY.

400

Bad Request

Missing required header APIKEY

400

Inactive APIKEY

APIKEY is in an inactive state. Please contact the developer or try again later.

400

Under Maintenance

APIKEY is in maintanance mode. Please contact the developer or try again later.

403

Host Blocked

Your Host address is blocked.

403

Host Not Whitelisted

Your Host address is not whitelisted.

403

IP Blocked

Your Ip address is blocked.

403

IP Not Whitelisted

Your IP adrdess is not whitelisted.