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

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.

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 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>
            }
        ]
    }
}