GETTING STARTED

The LCLXchange uses HTTP-based RESTful APIs and OAuth 2.0 for transaction authorizations. All API request and responses use JSON.

Note: The sample requests contained in this document are for reference only. You will not be able to run the examples as is. Please construct your requests based on your authorization token and data requests with your own data values.

Authentication and Authorization

The LCLXchange REST API utilizes the OAuth 2.0 protocol to authorize transactions to the LCLXchange server. OAuth enables third-party applications to obtain limited access to a web service.

When you log into the LCLXchange through our API, the website will generate a set of OAuth user ID and credentials. For every transaction, you must pass these credentials in the Authorization header using the bearer access token. The bearer token enables you to execute a transaction using your credentials.

The user access_token field contains the bearer token required for LCLXchange API transactions. Copy this token and add it to each of your service requests in the Authorization header.

As an example, request the following request will return the list of routes.

				// Example Request
curl -v -X GET 'https://www.lclxchange.com/api/route' -H "Content-Type: application/json" -H "Authorization: Bearer <access_token>"

To determine when an access token expires, either store this value in your code or handle the HTTP 401 Access Denied status code. when an access token expires, write code to either:

  • Keep track of the expires_in value in the token response. The value is expressed in seconds.
  • Handle the HTTP 401 Unauthorized status code.

Note: Reuse the same access token until it expires.

API Requests

This section provides information about what is required to generate an API Request.

Component Description
The HTTP Methods

GET - Requests data from the API

POST - Submits form like data to the API

PUT - Submits form like updates to the API

DELETE - Deletes a record or entry in the API

HTTP Request Header

Items such as Content type and Authorization header containing the access token.

The URL to the API Service

https://www.lclxchange.com/api

Query Parameters

Optional. Defines what data to return in the response. These types of values are items such as data item index, page navigation, filtering and sorting in an API response.

HTTP Request Body

A JSON formatted request for the GET, POST, PUT, and DELETE HTTP requests.

Query Parameters

The LCLXchange API GET calls are generally informational with the exception of responding to requests for freight rates. Because the results returned are informational, the API provides a suite of API requests to populate other calls. For example, when requesting available consols, the container type will be provided as an index, you will need to query the container types from the system and do your own mapping. It is important to note, that some of these requests will be filtered based on your user rights. Additionally. Some API calls allow you to filter and set the number of results you like to return. For these types of calls, see the details of the specific API call. Note: Not all parameters are available for all APIs.

The following table provides an overview of the types of query parameters the system may take depending on the request.

Parameter Data Type Description
index

integer

The index of the data record to return

rowsperpage

integer

The number of items to return in the results

offset

integer

The start index of the list of items that are to be returned. We currently use 0 (zero) as the start index. For example, an offset=0 and a rowsperpage=10 will return the first 10 items. An offset=1 and rowsperpage=10 will return items 11-20.

Below is an example to return the number of routes starting with an offset of 1 and a rowsperpage of 5.

				// Example Request
curl -v -X GET 'https://www.lclxchange.com/api/route?offset=1&rowsperpage=5' -H "Content-Type: application/json" -H "Authorization: Bearer <access_token>"

HTTP Request Headers

In the table below is the list of common HTTP request headers that the LCLXchange API uses.

Header Description
Authorization

The Authorization header is required to make API calls. Include the <access_token> in the call.

The syntax is: Authorization: Bearer <access_token>

Content-Type

The Content-Type is required for API calls with a request body

The syntax is: Content-Type: application/<format> where <format> is 'json'

HTTP Responses

The LCLXchange API returns a HTTP status code for each transaction. Additionally, all API requests return a JSON response body which may or may not include the target results. Each Rest API request will return an HTTP success or error code.

In the table below is the list of common HTTP responses that the LCLXchange API returns.

Status Code Description
200 OK

The request succeeded.

400 Bad Request

The request is not well-formed, syntactically incorrect, or does not pass the error checking.

401 Unauthorized

Authentication failed due to invalid authentication credentials.

Your First Request

To make REST API calls using the LCLXchange you will get your access token. Make sure you have registered an user account on the LCL Xchange before beginning this step.

Many programming languages support HTTP/JSON type requests. For the examples in this document we will use cURL to demonstrate the functionality. To start using the API it is recommended that you use either the cURL program on the command line or a API developer tool such as Postman.

Use the following links to get cURL or Postman.

Using the following request with your registered credentials, the request will return the access_token, expires_on, and user details.

				// Example Request
curl -X POST 'https://www.lclxchange.com/api/login' -H 'Content-Type: application/json' -d '{ "email" : "<email_address>", "password" : "<password>" }'

On a successful authentication the result will look something like:

				//Example Result
{
"user": {
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGiJIUzI1NiJ9.eyJpc3MiOiJMQ0xYY2hhbmdlIiwiYXVkIjoR0cHM6XC9cL3d3dy5sY2x4Y2hhbmdlLmNvbsImlhdCI6MTM1Njk5OTUyNCwibmJmIjoxMzU3MDAwMDAwLCJkYXRhIjp7ImlkIjoiMyIsImZpcnN0bmFtZSI6IkpvbiIsImxhc3RuYW1lIjoiQ2FyaXRhbiIsImVtYWlsIjoibmVpbC50YWxib3RAbGNseGNoYW5nZS5jb20ifX0.DKCxfJfRixbvknT86641ZiOhN4Yx9ZUXSa7aX1vcGo8", "expires_on" : 86400,
"firstname": "John",
"middlename": "",
"lastname": "Doe",
"email": "john.doe@lclxchange.com",
"enabled": "TRUE",
"lastlogin": "2018-12-11 07:41:03",
"company": {
"index": 1234,
"name": "Shipping & Freight",
"address1": "Suite 111",
"city": "New York City",
"state": "NY",
"postal": "11355",
"country": "UNITED STATES",
"phone": "+55 (55) 2341-1234",
"otilicense": "003920"
}
}
}