Core Concepts
- Rex Enage (Unlicensed)
Getting Started with the BBA API is simple. Jump right into the Core concepts below to learn more about its technical implementation. Explore the Technical reference section to know how to make the most of the wide range of resources available. Have a question? Contact our Support Team, we are here for you. We have your back.
Authentication
To use BBA APIs you need to follow an authentication process. Currently, BBA supports OAuth 2 protocol for authentication and authorization. OAuth 2 framework allows applications to obtain limited access to user accounts on an HTTP service. It delegates user authentication to the service that hosts the user account, and authorizes a third-party application to access the user account.
For a detailed explanation on how to implement this protocol, please visit the Official OAuth 2 RFC.
Libraries and tools
- REST client application such as Postman or SoapUI to test REST request and response in BBA Mastro services.
- jwt.io (JSON web toolkit) online encoder and decoder to debug access token. It can be installed also as google chrome extension.
Architecture style
BBA APIs are designed based on a REST architectural style. As such, it communicates over the HTTP protocol using HTTP request methods. The APIs use JSON as data exchange format.
Request structure
The base URL for the requests is currently: http://api.bbamastro.com
It will be changed to https://api.bbamastro.com in a near future.
Header
Most of the resources can be accessed only by authenticated users. After the user is successfully authenticated, the system provides an access token. The token must be included in the "Authorization" field of the HTTP header on each request.
Because the APIs use JSON as data format for interchange communication, the "Content-type" must be set to "application/json" for requests that contain JSON data.
The HTTP sample header below is the commonly used header for requests.
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX25hbWUiOiJnb2hhcmlrZ2FicmVseWFuQGdtYWlsLmNvbSIsInNjb3BlIjpbInJlYWQiLCJ3cml0ZSJdLCJleHAiOjE0ODA2ODY3NTMsInVzZXJJZCI6MTAsImF1dGhvcml0aWVzIjpbIlJPTEVfQURNSU4iLCJST0xFX0NPTVBBTllfQURNSU4iXSwianRpIjoiODg1YjMwMWItOGU4OC00OWU0LThkYzktMzZkNmRlZTUyOTAxIiwiY2xpZW50X2lkIjoiY2xpZW50YXBwIn0.6gn5-AibKa-RPkf0m1H2mh0HK97ZNSlSyoTtSCJyIHo Content-type: application/json
HTTP Methods
There are several HTTP methods used in the BBA system.
| Method Name | Description |
|---|---|
POST | This method is used for create new resources. |
GET | This method is used to get resources. |
PUT | This method is used to update all fields of a resource. |
PATCH | This method is used to update some fields of a resource. |
DELETE | This method is used to delete data. |
Data Types
There are several data types used in this system
| Name | Description |
|---|---|
Number | Numeric data type |
String | Alfa numeric data type |
Boolean | True or false |
| Date with format (yyyy-MM-dd) |
Response format
Responses from BBA system consists of:
- Response code: refer to the Error handling section on this page for further details on response codes.
- Response body: the content of the response in JSON format or file (PDF, CSV, etc).
Pagination
Some of our APIs resources support pagination under the following rules:
| Default page size | 20 |
|---|---|
| Maximum page size | 2000 |
Pagination parameters
| size | page size |
|---|---|
| page | page number |
| sort | sorting query |
Error handling
Every request to the API is replied by the system regardless if it is successful or not. The response code for success is 2xx. The table below provides a list of errors that may occur and how to solve them.
| Error code | Error message | Troubleshooting |
|---|---|---|
| unauthorized | Full authentication is required to access this resource | The user is not authenticated or an invalid access token is provided. To solve this issue, set "Authorization" with a correct access token in the header. Authorization: Bearer [access_token_here] |
| invalid_token | Access token expired: xxxx | The Access token expired. Get a new access token and set it in the header as follows: Authorization: Bearer [access_token_here] |
| 405 | Method Not Allowed | This error message occurs because of an invalid HTTP method. Check the documentation for the supported HTTP methods (GET, POST, PUT, DELETE). |
| Invalid Request | Validation issue | Incorrect request data was provided. In order to solve this error, check the "fieldErrors" data for the correct data. Example, the error below occurred because the field "name" is empty:
Make sure you provide all the required data. |
| 500 | Internal Server Error | Error on the system. Contact the developer to fix this issue. Example:
|
Terminology
| Term | Description |
|---|---|
| API | API (Application Program Interface) is a set of routines, protocols, and tools for building software applications. An API specifies how software components should interact and APIs are used when programming graphical user interface (GUI) components. |
| REST | REST (Representational State Transfer) is an architectural style for designing networked application that uses HTTP protocol to make a call between machines. |
| JSON | JSON (Javascript Object Notation) is a lightweight data-interchange format that easy for humans to read and write. It is easy also for machines to parse and generate. |
| Oauth2 | OAuth 2 is an authorization framework that enables applications to obtain limited access to user accounts on an HTTP service. |
| JWT | JWT (JSON Web Tokens) is an open, industry standard RFC 7519 method for representing claims securely between two parties. |
| Access Token | Access token is a token provided by the authentication server after the user is authenticated. The token must be used to access API resource. It has a lifetime and must be renewed when it expires. |
In this page