Technical In mid-2019, we launched our first APIs which enable you to build custom integrations between Appsembler Tahoe and other software platforms. This is an important step in enabling you to integrate Tahoe, our customer training software based on Open edX, into your existing business workflows.
These integrations usually require a developer to build. A developer on your team should be able to use this documentation, or you engage our Professional Services team. However, we are committed to helping you leverage these endpoints and want to guide you through our documentation.
We’ll start with an overview of APIs and then guide you through navigating the API documentation and currently available API Endpoints. If you’re already familiar with APIs, feel free to skip to the end or go check out our API documentation.
Background
What is an API?
An API – Application Programming Interface – enables programmers to pull data from an application or send data to an application through other applications and websites.
It is a set of protocols, routines, functions and/or commands that programmers use to develop software or facilitate interactions between different systems.
APIs consist of three parts. APIs enable 1) users to send requests from a 2) client to a 3) server, which returns a response.
- User: person making a request
- Client: computer sending the request to the server
- Server: computer responding to the request
These API requests and responses traditionally occur via the Hypertext Transfer Protocol (HTTP), the same protocol used by your browser to retrieve webpages.
HTTP requests include the following: URL, Method, List of Headers, Body.
- URL: the client uses this to tell the server what it wants to interact with
- Method: the client uses this to tell the server what kind of action to take
- GET: requests data from a server
- POST: sends changes from the client to the server
- PUT: revises or adds to existing information
- DELETE: deletes existing information
- Headers: provide metadata about the request
- Body: the data the client wants to send the server
In the HTTP response, the server responds with data and a three-digit status code.
The data returned in the body is usually in a text format – most commonly XML or JSON.
An XML (Extensible Markup Language) file is a hierarchy of elements, which contain the data.
JSON (JavaScript Object Notation) is a format that consists of arrays and objects. An array is a list of related items in order, separated by commas. An object is a set of named properties describing these items.
Note: our APIs at Appsembler return data using the JSON format.
API Endpoint: A single, callable URL that takes in data and performs an action. The endpoint is where the API interacts with other systems, via requests and responses.
API Key: A unique string of letters and numbers used for authorization and verification when accessing the API.
Appsembler APIs
Navigating the API Documentation
At the moment, our API documentation describes our API Endpoints (URLs), also called resources or methods. Each one also has a designated request method and each one includes two sections: Parameters and Response. Some include handy examples.
Endpoint: The aforementioned, single, callable URL that takes in data and performs an action.
API Action / Request Method: The aforementioned actions / methods for interacting with data: GET, POST, PUT, and DELETE.
Parameters: Information (sometimes required) that you can supply as part of the request.
Response: This is what you get back from the server. The response either comes back with a 200 code and the data that you want (JSON), or another code explaining why your request failed.
Available API Endpoints
Registration
API Endpoints available for registering users on Tahoe from a third-party system.
Collect initial registration information from users through an external system (including information that Tahoe doesn’t need like instance: title, department, company, etc) and then send the relevant information over to Tahoe to start the learner’s registration process there.
Enrollment
API Endpoints available for enrolling learners in courses on Tahoe from a third-party system.
Use an external system to enroll users in courses by sending the relevant information over to Tahoe to start the learner’s enrollment process there.
Course Catalog
API Endpoint to retrieve course identifier data on Tahoe from a third-party system.
Present course catalog information in other locations, outside the LMS.
The level of integration ranges in scope:
- showing the latest course titles and links on the company homepage
- pulling over course titles, descriptions, and dates into an e-commerce system to let prospective learners browse them
User
API Endpoint to retrieve user identifier data on Tahoe from a third-party system.
Use these from an external system to retrieve Tahoe user identifier information.
