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/afl/api/v1/user/get/profile?uid=123
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. Follow the steps for successful integration of the application with epixelmlmsoftware,
Log in as system super admin,
Find API Menu from top menubar - Administartion > API > Applications
Register Client Application - by clicking the add button
The client application must furnish the following details during the app registration -
Project/Application name
API Version
Client type - Mobile, Web backend, or Browser-based application.
Generate apikey (app token)
Choose the created application and click save to generate apikey for your 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.
Register or add an API admin user - an admin gets permission for all endpoints and manages user data.
Add outgoing configuration for your application to use webhook and SSO services.
Choose application, platform, domain details, and authentication details.
Get Encryption keys, first go to application edit option -
collect encryption codes from the bottom of the edit form.
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 Response Structure
Basic error structure
Validation error structure
Common Error Responses
Last updated