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 -
This call gets the profile details of the user 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 registration -
  • 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 are 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 depicts a sample API request using the 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 "apikey: {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 gets 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 sample 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 -
During Integration of Client Application with Epixel MLM API, Must register an API Admin
user for access non-user API endpoints such as ‎Countries States etc.
An API Admin can access all endpoints and manage users' data using uid in request query params.
Also, collect encryption keys on the basis of the client platform.

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
1
{
2
"status_code": <HTTP response status code>,
3
"errors": {
4
"type": "<Error name>",
5
"detail": [
6
{
7
"message": "<Detailed error description>"
8
}
9
]
10
}
11
}
Copied!
Validation error structure
1
{
2
"status_code": 400,
3
"errors": {
4
"type": "Validation Error",
5
"detail": [
6
{
7
"attribute": "<Field Name>",
8
"message": <Array of messages>
9
}
10
]
11
}
12
}
Copied!
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.
Last modified 6d ago