This FAQ will explain what the REST protocol is, how the BB-400 provides its REST server implementation and a list of REST communication methods on the BB-400.

What is REST?

REpresentational State Transfer is a software architectural style that defines a set of methods to build a web Application Programming Interface (API). REST is one of the most popular types of API, due to its simplicity and client-friendly nature. The major benefit of REST is statelessness, which means that the server does not store any information about the client. Instead, every request from the client contains all the information for the server to process the request.

 

http://www.brainboxes.com/files/pages/support/faqs/bb-400-faqs/logos/rest logo.png

The REST API is a style of data transfer that is language-independent. The objects in REST are always manipulated from the Uniform Resource Identifier (URI), and payloads are used to send and return information that is too large to be handled as a parameter. The payload can be of a variety of different formats, including HTML, JSON or XML.

 

URL

The BB-400 IO uses a HTTP based RESTful API, and the format of the URL is:

http:[//authority][path]

where authority is the IP address or name of the BB-400 followed by a colon ( : ) and port number. For example:

http:[//IPaddress:portnumber][/path] or http:[//name:portnumber][/path]

The name of the BB-400 is by default “bb400-XXXX“, where XXXX represents the last 4 digits of the MAC address. The default port number for REST is 9000, which can be verified by going to the web admin IO page and selecting REST:

http://www.brainboxes.com/files/pages/support/faqs/bb-400-faqs/How-do-I-use-Python-to-control-the-IO-over-REST-on-my-BB400-WebAdminIO-Port-Number.png

The path section of the URL denotes the information required, e.g. “/io” refers to the IO status of the BB-400.

Combined with the authority and path information, examples of potential BB-400 URLs are:
http://192.168.0.36:9000/io
http://bb400-00c0:9000/io.

REST and the BB-400 IO line status

The BB-400 provides a REST server implementation that can be used to receive and modify the status of the IO lines. The BB-400 allows users to request the input and output values from the REST server, and returns the response as a payload. Data is passed and returned using a JSON format. For more information about JSON, please refer to the following link: https://www.json.org/.

REST requests

The verbs that the REST server on the BB-400 uses are GET and POST.

GET requests allow the user to retrieve information without modifying the original state, even if the requests are sent multiple times. A GET request can be used to obtain the input or output status of the IO lines on the BB-400.

POST requests allow the user to modify the original information. If the POST request is successful a “200 OK” status will be returned, otherwise an unsuccessful status code will appear. A POST request can be used to modify the output values of the IO lines on the BB-400.

The following table lists the different GET and POST requests available:

 

Path Verb Description Example
/io GET   Retrieve input and output state 
 {
inputs: [0,0,0,0,0,0,0,0],
outputs: [1,1,1,1,1,1,1,1]
 } 
/io/inputs GET Retrieve input state  [0,0,0,0,0,0,0,0]
/io/outputs GET Retrieve output state [1,1,1,1,1,1,1,1]
/io/inputs/3 GET Retrieve IO 3 input state 0
/io/outputs/7  GET Retrieve IO 7 output state 1
/io/outputs  POST  Sets all IO line output values [0,0,0,0,1,1,1,1]
sets IO 0-3 to open
and IO 4-7 to closed
/io/outputs/3   POST  Sets IO 3 value 1
sets IO 3 to closed

 


 

BB-400 REST communication methods

There are a number of different ways in which the BB-400 IO can communicate using REST, all of which use the GET and POST commands.

Below is a list of FAQs for communicating with the REST API on the BB-400 via:

  1. A web application, POSTMAN - (FAQ How to use a REST API on the BB-400 from a web application)
  2. A Windows application, Powershell - (FAQ How to communicate with the REST server on the BB-400 via Powershell)
  3. cURL commands - (FAQ How to communicate with the REST API on the BB-400 using cURL)
  4. Python - (FAQ How do I use Python to control the IO over REST on my BB-400).