Texada SRM APIs

How to access, test and use Texada’s SRM APIs.

Quick Reference

• Texada’s SRM currently supports APIs built on two different technologies: PROIV and Flask. Both types of APIs are documented using Swagger.
• Texada’s Swagger documentation can be accessed at the following URLs:
  • PROIV: https://documentation.texadasoftware.com/ 
  • Flask: https://naoc1.texadasoftware.com:8009/docs/#/ 
• Using the Swagger documentation, you will be able to browse and test out the various API methods:
  • Click on a method to view its details, including its type, path, description, expected input, and possible responses.
  • Click the “Try it out” button to input some data and receive a sample response.
  • Use the “Example Value | Model” toggle to switch between two different ways of viewing the method’s output:
    • Example Value: Displays a sample response.
    • Model: Displays the generic format of the response, including variable names and types.
• Flask APIs:
  • Texada’s Flask APIs can be accessed using any web browser, curl command, or HTTP client application at the following URL:
    • https://{serveraddress}:{Port}/WebServices/rws/api/dev/{endpoint}
  • Before you are able to use Texada’s Flask APIs, you will need an authorization token. This token can be obtained using the APIs themselves, by submitting a request via one of two authentication methods:
    • /auth/login: Log in using an SRM Operator email address and password.
    • /auth/web_api_key: Log in using a Web API Key.
  • The Web API Keys used to authenticate via the /auth/web_api_key method are managed in Texada SRM, at System Maintenance → Configure System Settings → Security → Web Services API Keys. Note that this screen is not available to all SRM Operators.

In This Article

• Introduction
• PROIV and Flask
• Swagger Documentation
  • Introduction to Swagger
  • Accessing Texada’s Swagger Documentation
  • Testing a Method
• Flask APIs
  • Connecting to Texada’s Flask APIs
  • Authorization
    • /auth/login
    • /auth/web_api_key
  • Managing Web API Keys
• PROIV APIs
  • Authorization

Introduction

Like many software companies, Texada offers a number of APIs which subscribed clients can use to interact with SRM’s data. The following article will detail how to access and use Texada SRM’s APIs.

PROIV and Flask

Texada SRM currently supports APIs built on two different technologies: PROIV (pronounced pro-four) and Flask. The uses of these two APIs are complementary, and both are included in Texada’s SDK. If you are searching for a particular endpoint and cannot find it in one location, try searching for it in the other location.

• PROIV
  PROIV endpoints tend to focus more on features that involve complex calculation, logic, or editing documents.
• Flask
  Flask endpoints tend to focus more on reading data and making minor updates.

Swagger Documentation

Introduction to Swagger

Swagger is an industry documentation standard that Texada uses to document its APIs. By accessing Texada’s Swagger documentation, you can view, interact, and experiment with Texada’s APIs (both PROIV and Flask). This documentation can be accessed from your web browser, and is an invaluable resource for understanding what Texada’s APIs are capable of and how to use them.

Accessing Texada’s Swagger Documentation

You can access Texada’s Swagger documentation at the URLs below. It is highly recommended to bookmark these links for future reference.

• PROIV: https://documentation.texadasoftware.com/ 
• Flask: https://naoc1.texadasoftware.com:8009/docs/#/  

When you navigate to one of these addresses, you will be taken to a page similar to the one below.

Fig.1. The home page of the Swagger documentation for Texada’s Flask APIs, showing the Explore bar and the accounts_receivable API group.

This page contains a list of all the methods that Texada has made available with this API. Methods are grouped together by module; for example, Fig. 2. below shows a sample of the methods within the “asset” module:

Fig. 2. A snippet of the API methods available under the asset module.

Modules can be expanded and collapsed by clicking anywhere on the title bar.

Each API method within a module (e.g. GET/assets/) can be expanded by clicking on it. Expanding a method will provide you with detailed information about that method.

Fig. 3. Expanded information panel for the GET/assets/{product_no} method.

1. Method Type
   Indicates the method’s type. There are five types of methods used in Texada’s APIs:
   • GET: Retrieves information about a resource.
   • POST: Creates a resource.
   • PUT: Updates a resource.
   • PATCH: Updates part of a resource.
   • DELETE: Deletes a resource.
2. Method Path
   The method’s path.
3. Method Description
   A brief description of what the method does.
4. Try it out Button
   This button allows you to experiment with the method by entering your own parameters and submitting a ‘dummy’ request. See “Testing a Method” for more information.
5. Method Parameters
   A list of the method’s input parameters. The following information is included for each parameter:
   • Name: The parameter’s name.
   • Required: Indicates whether the parameter is required.
   • Data Type: The parameter’s data type (string, date, integer, file, etc.)
   • Type: The parameter’s type (header, path, query, body, etc.)
   • Description: A brief description of the parameter.
6. Response Content Type
   Indicates the content type of the responses in the section below. Click the drop-down to switch between possible response content types. Currently, all Texada API methods use JSON as a response format.
7. Responses
   A list of responses that can be returned by this method. This list will generally begin with a 200-series code (successful response), followed by one or more 400- or 500-series codes (client/server error responses). Note that not all possible responses are documented here. The following information is included for each possible response:
   • Code: The HTTP status code of the response.
   • Description: A description of the response.
   • Response: A sample response body. Use the “Example Value | Model” toggle to switch between two ways of viewing the response (Fig. 4.):
     • Example Value: Displays a sample response.
     • Model: Displays the generic format of the response, including variable names and types.

Fig. 4. Using the “Example Value | Model” toggle, you can switch between two different ways of viewing a method’s responses: a sample response (left) or a generic model (right).

Testing a Method

Each API method can be tested directly from the Swagger documentation. This is a useful feature that allows you to experiment with different inputs and familiarize yourself with what each method will output based on the inputs you use.

To test a method: 

1. Locate the method you want to test in the Swagger documentation and click it to view its details.
2. Click the “Try it out” button found in the top-right corner of the details panel. This will cause input fields to appear next to each of the method’s parameters (Fig. 5).
3. Fill out the input fields using the data you want to test. Fields marked with a red asterisk () are required.
4. Click “Execute” to submit your request.
5. Scroll down to the Responses section of the details panel to see the results of your request (Fig. 6). You will see the HTTP response code, response body, and response headers generated by your request. Click “Download” next to the response body to download a copy of the response.
6. Click “Clear” to clear the Responses section. Modify your inputs and click “Execute” to submit another request using the new inputs.

Fig. 5. After clicking “Try it out” in a method’s details panel, input fields will appear for each of the method’s parameters, allowing you to experiment with different inputs. Click ‘Execute’ to call the method using the parameters you specified.

Fig. 6. The Responses section of a method after clicking the “Execute” button. The “Curl” section shows the curl command corresponding to your request. The “Request URL” section shows the request URL corresponding to your request. The “Server response” section shows the HTTP response code, body, and headers of the response generated by your request.

Flask APIs

Connecting to Texada’s Flask APIs

You can connect to Texada’s Flask API servers using any web browser, curl command, or any HTTP client application (like Postman).

The URL structure to access these servers is as follows:

https://{serveraddress}:{Port}/WebServices/rws/api/dev/{endpoint}

• {serveraddress} is the URL of your Texada SRM installation, for example naoc6.texadasoftware.com. To learn this address, open your OpenClient login page for Texada SRM, then right-click the Login button and select “Copy link address”. The server address is the portion of this URL after “https://” and before the colon “:”.
• {Port} is the port number of your Texada SRM installation, and depends on both your region and whether you are working in a production environment or play environment:
  • North America Production: 8008
  • North America Play: 8009
  • APAC Production: 8012
  • APAC Play: 8013
• {endpoint} is the particular API endpoint you would like to access. See “Swagger Documentation” to learn how to access the list of endpoints.

Authorization

In order to communicate with Texada’s Flask APIs, you will need an authorization token. This token can be obtained using the APIs themselves, by submitting a request via one of two authentication methods:

• /auth/login: Log in using an SRM Operator email address and password.
• /auth/web_api_key: Log in using a Web API Key.

Both of these methods can be found in the “auth” section of the Flask API Swagger documentation. 

Fig. 7. When filling out the ‘authorization’ field, always make sure to follow the “Bearer <token>” format.

/auth/login

Fig. 8. The /auth/login method.

This method accepts a LoginUser object containing a client ID, company ID, email, and password, and returns an auth token and refresh token which can be used in subsequent requests to the Texada Flask API. Use this method when you wish to access the API with a user login.

Input: 

LoginUser {

     clientID*      string
     maxLength:     20
     minLength:     3
                    The client ID.

     companyID*     number
     maxLength:     8
     minLength:     1
                    The ID of the company for which the user is requesting access.

     email*         string($email)
     maxLength:     50
     minLength:     1
                    The user’s email address.

     password*      string($password)
     maxLength:     80
     minLength:     1
                    The user’s password.

}

Output:

Tokens {

     authToken      string
                    The authentication token.

     refreshToken   string
                    The refresh token.

}

/auth/web_api_key

Fig. 9. The /auth/web_api_key method.

This method accepts a WebAPIKey object containing a client ID, operator ID, and Web API Key, and returns an auth token and refresh token which can be used in subsequent requests to the Texada Flask API. Use this method when you wish to access the API using a Web API Key issued by SRM; see “Managing Web API Keys” for more information.

Input:

WebAPIKey {

     clientID*      string
     maxLength:     64
     minLength:     3
                    The client id.

     operatorID*    string
     maxLength:     18
     minLength:     1
                    The operator id.

     webApiKey*     string
     maxLength:     32
     minLength:     1
                    The Web API Key issued by SRM.

}

Output:

Tokens {

     authToken      string
                    The authentication token.

     refreshToken   string
                    The refresh token.

}

Managing Web API Keys

The Web API Keys used to authenticate via the /auth/web_api_key method are managed in Texada SRM. You can review, add, copy, and delete API Keys from the Maintain Web Services API Keys screen, located at System Maintenance → Configure System Settings → Security → Web Services API Keys.

Fig.10. The Maintain Web Services API Keys screen in Texada SRM.

PROIV APIs

Authorization

Unlike with Texada’s Flask APIs, there is no need to authenticate in advance when accessing Texada’s PROIV APIs. Instead, you will need to pass your API key with each request you make. For more information about this process, please contact Texada support.