Getting Started: API

Note: This tutorial describes how to use the Robotics Club API on a technical level. For an overview on the purpose of this project visit Project Overview.

Overview

The API exposes REST endpoints for various features. The API is self documented and can be viewed by visiting https://www.roboticsclub.org/docs/.

Note: Using your user credentials you will be able to interact with all read-only endpoints and user lookup services. At the time of this writing the only endpoints you will not be able to successfully interact with both your user credentials and standard project credentials are /users/:id/email/ and /users/:id/rfid/ which provide the ability to email to a user and update their RFID respectively. These are privileged operations and your projects must have special permission to use them. The RFID endpoint is only provided for the CardReader project(to first populate RFID field). If you believe your project needs the email endpoint please contact root.

The "concrete" API endpoints such as /tshirts/, /users/, etc. should be self explanatory. The more "abstract" endpoints such as the User lookup services and /channels/ and /api_requests/ are described below:

channels - The purpose of channels is to provide a centralized communication hub between all projects and users. Classically projects would not interact with other projects and services. This encourages projects to interact. Channels do not enforce what data is transmitted or how it is structured but instead just the medium. At the time of this writing the Python and Arduino libraries only support Ethernet and Wifi links, however due to the stateless design of the medium XBEE, RS232, etc. to Ethernet or Wifi bridges could easily be created if projects need them. Channels are accessible from both the API and Admin interface making it easy for Users and Projects to work with them alike. For more details check out the 'Channels' section.
API Request - An APIRequest is created whenever a successfully authorized request to the lookup endpoints(/magnetic/ and /rfid/), /users/:id/rfid/, or /users/:id/email/ is made. Since these are considered special operations they are logged via these objects. On a User's setting's page there is a field Recent Club Acitivty which is populated using these objects. At the time of making a request you can provide the optional 'meta' field which is a editable String used to describe what the request is for. For example, in Tooltron's case this is the name of the machine the User was requesting access for. In the response of a request(if successful) there will be a field api_request which is the ID of the APIRequest created. Using the APIRequest endpoint you can update the meta and success fields for that APIRequest at any time. The success field is similar to the meta field except it is a boolean value used to represent whether a User was successfully authorized(Tooltron trained for machine, Fridgetron enough money on tab, etc.) to complete an operation after they were authenticated(obtaining user id).

Note: only Users or Projects who made the original request can edit the corresponding APIRequest

Project Usage

User credentials can be used to browse the API and interact with it from a browser however User credentials are not supported outside testing or by the API language bindings. Projects have their own credentials consisting of a public & private key. When creating a project through the Admin interface you may have noticed a field private_key. Using this value and your public key, also known as your project id, your project can use the API by setting the PUBLIC_KEY and PRIVATE_KEY HTTP headers(language bindings already do this).

Warning: Do not commit your private key to public repositories

Channels

Creating a Channel

Channels can only be created through the Admin interface. Each channel name must be unique. Provide a description so other users & projects know what to expect from reading your channel or what to write to it.

Writing to a Channel

Admin

On a channel's edit page by clicking any Save operation the value will be considered 'new' regardless of if the value was changed or not since the updated_datetime field would be changed.

API

PUT or PATCH request to '/channels/:id/'. Consult https://www.roboticsclub.org/docs/ for more information.

Read from a Channel

Admin

Look at the value field.

API

At the time of this writing only polling a channel is supported. In the future a server-push/websocket option should be implemented reducing overhead.