Getting Started Tutorial This simple tutorial will introduce you to the DLAP API. It demonstrates authenticating, creating a course, creating some derivative courses, creating a user, and enrolling users in derivative courses---all of which can be done using a web form in your browser. **To run this tutorial you will need to have administrator access to a domain, which your sales representative should have already set up for you.** Finding the Buzz API Server The URL for making API calls is: https://backgroundapi.agilixbuzz.com/cmd The hostname in this URL is the background-processing endpoint, which is the correct endpoint for integration and scripted use. Buzz has separate endpoint hostnames for user-interactive traffic and for testing backoff handling — see API Time Limiting for when to choose one of those instead. Try browsing to the URL above. You should receive a response with a message like "No API command specified" from the server. This is good. It means you’re pointing your browser to the right place. Calling GetStatus Now let’s run a basic GetStatus command. You can use this call to request product, version, and status information from the server. To run this command, add two name-value pairs to the query string (cmd and level), as shown below. Query String cmd=getstatus&level=2 The full URL would be https://backgroundapi.agilixbuzz.com/cmd?cmd=getstatus&level=2 *NOTE: The GetStatus command is one of the only calls you can make without first authenticating. You must authenticate before you will be allowed to execute most API calls.* Making POST requests Some API commands require an HTTP POST with a message body. In our examples we'll use the curl command line tool to make these requests. In addition, the API server has an API Console you can use to make API requests, including ones that require a POST. The table of contents has a link to the API console. Note: the API Console form is not designed for you to call from your programs; it is simply a convenience form that allows you to manually execute and test some API calls. In code, you call DLAP directly as described in Command Usage. Authentication **Note:** This tutorial signs in interactively with a username and password because it is a hands-on walkthrough. Acquisition of the API bearer token used in this scenario is different from how it would happen in a real integration, and you won't see the token sent with the requests, as it's part of the HTTP headers which are not displayed in the console. That said, that hidden authentication header is generally the only difference between requests made in the API Console and those that you would make through scripts or code that you write, making the API Console a good way to test out the format of the API calls you're going to make in code. In your code, you will need to acquire the authentication token using an OAuth 2.0 Application Identity, which is more secure and involves no password at all. The working sample code demonstrates the OAuth flow end-to-end. To sign in to the API Console: 1. Open the API Console. 2. Click the small **Sign in** link at the right end of the toolbar at the top of the page. 3. Enter your username in the form userspace/username — for example testschool/admin — along with your password, and click **Sign in**. If your account uses multi-factor authentication, you will also be prompted for your second-factor code. The console holds the resulting session token (the link changes to **Sign out**) and attaches it to each request you send; when the session expires, the console prompts you to sign in again. The curl versions of the examples below show the same requests as you would make them from code, with the access token — acquired via OAuth 2.0 Application Identity in a real integration — passed explicitly from the TOKEN shell variable. Creating a Course Now that we are authenticated, we'll create our first course using the CreateCourses command. We’ll create a sample course with the title “Math” and give it an external reference of "course1". Verb POST Query String cmd=createcourses Post Data ``` { "requests": { "course": [ { "title": "Math", "domainid": "//testschool", "reference": "course1", "schema": "3" } ] } } ``` In this example the domainid is referenced by its domain userspace "/testschool" (see Entity IDs). The course's reference is reserved for any data you wish to store. The reference is useful as an unique reference that you can pass in. In this case "course1" is specified as the reference and can be used later to identify this newly created course. Example request: curl https://backgroundapi.agilixbuzz.com/cmd?cmd=createcourses -H "Content-Type: application/json" -d "{\"requests\": {\"course\": [{\"title\": \"Math\", \"domainid\": \"//testschool\", \"reference\": \"course1\", \"schema\": \"3\"}]}}" -H "accept: application/json" -H "Authorization: Bearer $TOKEN" You can check the response JSON to verify that the Math course was created successfully. Listing Courses Now that we’ve created a course, we can use the ListCourses call to see a list of available courses in a domain. Notice that this call is passed using an HTTP GET request. Verb GET Query String cmd=listcourses&domainid=<domainid> Example request: curl "https://backgroundapi.agilixbuzz.com/cmd?cmd=listcourses&domainid=//testschool" -H "accept: application/json" -H "Authorization: Bearer $TOKEN" In the JSON that is returned, you can see the newly created Math course. Creating Derivative Courses Next we will call the CopyCourses command to create derivative courses. You typically create derivative courses if you have multiple classes that teach the same material but possibly at a different time, or with a different set of students, or with a different instructor. We will create two derivatives of the Math course we just created. Verb POST Query String cmd=copycourses Post Data ``` { "requests": { "course": [ { "title": "Math - Section 1", "courseid": "//testschool/course1", "domainid": "//testschool", "reference": "mathsection1", "action": "DerivativeCopy" }, { "title": "Math - Section 2", "courseid": "//testschool/course1", "domainid": "//testschool", "reference": "mathsection2", "action": "DerivativeCopy" } ] } } ``` In this example the courseid is referenced by the "course1" key that we specified earlier. Using the domainid as the context we reference the courseid as "//testschool/course1". Example request: curl https://backgroundapi.agilixbuzz.com/cmd?cmd=copycourses -H "Content-Type: application/json" -d "{\"requests\": {\"course\": [{\"title\": \"Math - Section 1\", \"courseid\": \"//testschool/course1\", \"domainid\": \"//testschool\", \"reference\": \"mathsection1\", \"action\": \"DerivativeCopy\"},{\"title\": \"Math - Section 2\", \"courseid\": \"//testschool/course1\", \"domainid\": \"//testschool\", \"reference\": \"mathsection2\", \"action\": \"DerivativeCopy\"}]}}" -H "accept: application/json" -H "Authorization: Bearer $TOKEN" You can see a response for each of the two courses that are created. You can also list all courses by re-running the ListCourses command. Creating Users Next we will call the CreateUsers2 command to create two users: one user that we will later enroll as a course teacher, and one user that we will later enroll as a student. Verb POST Query String cmd=createusers2 Post Data ``` { "requests": { "user": [ { "username": "teacher", "password": "cCMUU9WDr83FCY8Y", "firstname": "Elizabeth", "lastname": "Allen", "email": "elizabeth.allen@school.edu", "domainid": "//testschool", "reference": "userteacher" }, { "username": "student", "password": "nbvLzpGfLrm57LsV", "firstname": "Charles", "lastname": "Brown", "email": "charles.brown@school.edu", "domainid": "//testschool", "reference": "userstudent" } ] } } ``` For each user we specify values for the username, password, name, email, and reference. The reference value is supposed to be an external reference; we specify values of "userteacher" and "userstudent", which we later use when we enroll the users in a course. Example request: curl https://backgroundapi.agilixbuzz.com/cmd?cmd=createusers2 -H "Content-Type: application/json" -d "{\"requests\": {\"user\": [{\"username\": \"teacher\", \"password\": \"cCMUU9WDr83FCY8Y\", \"firstname\": \"Elizabeth\", \"lastname\": \"Allen\", \"email\": \"elizabeth.allen@school.edu\", \"domainid\": \"//testschool\", \"reference\": \"userteacher\"}, {\"username\": \"student\", \"password\": \"nbvLzpGfLrm57LsV\", \"firstname\": \"Charles\", \"lastname\": \"Brown\", \"email\": \"charles.brown@school.edu\", \"domainid\": \"//testschool\", \"reference\": \"userstudent\"}]}}" -H "accept: application/json" -H "Authorization: Bearer $TOKEN" You can see one response for each of the two users that are created. Listing Users You can now see the two users (teacher and student) that were added by calling the ListUsers call. Verb GET Query String cmd=listusers&domainid=<domainid> Example request: curl "https://backgroundapi.agilixbuzz.com/cmd?cmd=listusers&domainid=//testschool" -H "accept: application/json" -H "Authorization: Bearer $TOKEN" In the JSON that is returned, you can see in addition to the admin user, the student and teacher user now exist. Enrolling Users in Courses Finally let's enroll the Teacher as a teacher in the "Math Section 1" course and the Student as a student in the same course using the CreateEnrollments command Verb POST Query String cmd=createenrollments Post Data ``` { "requests": { "enrollment": [ { "userid": "//testschool/userstudent", "entityid": "//testschool/mathsection1", "flags": "131073", "status": "1", "startdate": "2010-05-01T12:00:00.0Z", "enddate": "2010-08-30T12:00:00.0Z" }, { "userid": "//testschool/userteacher", "entityid": "//testschool/mathsection1", "flags": "4958793891840", "status": "1", "startdate": "2010-05-01T12:00:00.0Z", "enddate": "2010-08-30T12:00:00.0Z" } ] } } ``` Example request: curl https://backgroundapi.agilixbuzz.com/cmd?cmd=createenrollments -H "Content-Type: application/json" -d "{\"requests\": {\"enrollment\": [{\"userid\": \"//testschool/userstudent\", \"entityid\":\"//testschool/mathsection1\", \"flags\": \"131073\", \"status\": \"1\", \"startdate\": \"2010-05-01T12:00:00.0Z\", \"enddate\": \"2010-08-30T12:00:00.0Z\"}, {\"userid\": \"//testschool/userteacher\", \"entityid\":\"//testschool/mathsection1\", \"flags\": \"4958793891840\", \"status\": \"1\", \"startdate\": \"2010-05-01T12:00:00.0Z\", \"enddate\": \"2010-08-30T12:00:00.0Z\"}]}}" -H "accept: application/json" -H "Authorization: Bearer $TOKEN" You can see one response for each of the two enrollments. Error Handling Most DLAP requests return errors inside a response document with a 200 OK response. Some APIs like GetResource that are expected to be used directly from a web browser, or are expected to return non-document responses will use HTTP response codes other than 200 OK to return errors. HTTP response codes other than 200 OK could also be caused by intermediate internet nodes, so they must be examined for all APIs. There are several response codes that must be handled specially. 429 Too Many Requests is one of those. If you receive this response code, check the other headers and use the Retry-After to determine when you should retry the request. 503 Service Unavailable is another one to look out for. This can be returned when either the specific API server your request got routed to is overloaded, or one of the backend services it uses is overloaded. These responses will also include a Retry-Only header in the response indicating when you should retry the request. Failure to handle HTTP response codes properly may result in less timely responses.