Dojo Learning REST API

This is an overview of the REST API for the Dojo Learning online training service, which allows external clients to directly access and interact with the data layer of Dojo. This API is a free service for all users of Dojo, however we do enforce certain restrictions on the use of the API to ensure a high level of quality access for all.

Service Limits

• 1,000 requests per free user account per day.
• 10,000 requests per paid user account per day.
• Downloading data through the API counts towards your monthly bandwidth usage.

If you have ideas for using our API that could go over these limits, please send us an email at development@dojolearning.com. We'd love to chat with you and see how we might be able to work together to make it happen.

Table of Contents

Request Format Access Point Common Parameters Response Format Service Introspection Error Responses Client Libraries Client Downloads Client Usage Examples Lessons lesson.search lesson.topics lesson.list lesson.newest lesson.popular lesson.subscribed lesson.instructing lesson.summary lesson.chapter lesson.subscribe lesson.unsubscribe lesson.learners

Journal journal.list journal.unread journal.entry journal.reply Lounge lounge.topics lounge.threads lounge.thread lounge.post lounge.reply Notes notes.get notes.save People person.profile person.lessons person.subscribed

Request Format

Access Point

The access point for the Dojo Learning API is:

http://api.dojolearning.com/rest-action

This is the base URL for each request. The specific method request is appended to this URL, followed by additional parameters for GET requests. For example:

http://api.dojolearning.com/rest-action/lesson.topics?user=USER&apikey=APIKEY

Common Parameters

There are a few common parameters which are shared by all request methods. These are:

• user – REQUIRED – The username from your Dojo Learning account. You must have a Dojo Learning account in order to access the API.
• apikey – REQUIRED – Your API Key, a randomly generated key that verifies you have access to the specified user account in Dojo. You can obtain your API Key by logging into Dojo Learning and going to the developer area.
• format – OPTIONAL – This parameter allows you to specify the format you would like to receive your responses in. If not specified, the default format is "json". Valid formats are "json" and "xml".

Response Format

Responses from the Dojo Learning REST API are sent in JSON format. JSON is a popular, lightweight data-interchange format based on a subset of the JavaScript programming language syntax, however it is completely language independent and libraries for reading and writing JSON are available for all modern programming languages. In fact, as of PHP version 5.2, JSON support is even built into the core PHP language.

Service Introspection

If you specify no method in your request, such as the following, the API will return a list of all available methods including their description and a list of additional parameters that they require. To see this list, use the following request format:

http://api.dojolearning.com/rest-action?user=USER&apikey=APIKEY

This will return a data structure that looks like the following:

{
	"lesson.list": {
		"description": "Returns 10 lessons in the specified topic",
		"parameters": ["topic","offset"],
		"method": "GET"
	},
	"lesson.newest": {
		"description": "Returns the 10 newest lessons",
		"parameters": [],
		"method": "GET"
	}
}

Please note: An introspection request is performed upon each object instantiation in the client libraries, but does not count towards your daily usage limits.

Error Responses

Here is a sample error response, including the HTTP status header:

HTTP/1.1 500 Internal server error

{
	"code": 500,
	"msg": "Internal server error"
}

Return to top

Client Libraries

While you are free to access this API directly from any programming language you choose, we also make client libraries available for the following languages:

Client Downloads

• PHP – Download
• Ruby – Download
• Python – Download

The client libraries are licensed under the open source LGPL license, which allows for embedding in both open or proprietary applications.

Client Usage Examples

PHP client usage:

<?php

include_once ('dojolearning.php');

$dojo = new DojoLearning ('user', 'apikey');

$topics = $dojo->lesson_topics ();

foreach ($topics as $topic) {
    printf ('<h2>%s</h2>', $topic->name);

    $lessons = $dojo->lesson_list ($topic->id);

    foreach ($lessons as $lesson) {
        printf ('<a href="%s">%s</a><br />', $lesson->url, $lesson->title);
    }
}

?>

The PHP client requires PHP 4.3 or greater, as well as the following extensions:

• Overload
• JSON
• cURL

Ruby client usage:

require 'dojolearning'

dojo = DojoLearning.new('user', 'apikey')

topics = dojo.lesson_topics()

topics.each { |topic|
	puts '<h2>%s</h2>' % [topic['name']]

	lessons = dojo.lesson_list(topic['id'], 0)

	lessons.each { |lesson|
		puts '<a href="%s">%s</a><br />' % [lesson['url'], lesson['title']]
	}
}

The Ruby client requires the following libraries:

• RubyGems
• JSON
• SimpleHTTP

Python client usage:

from dojolearning import DojoLearning

dojo = DojoLearning ('user', 'apikey')

topics = dojo.lesson_topics ();

for topic in topics:
	print '<h2>%s</h2>' % topic['name']

	lessons = dojo.lesson_list (topic['id'], 0)

	for lesson in lessons:
		print '<a href="%s">%s</a><br />' % (lesson['url'], lesson['title'])

The Python client requires the following library:

• simplejson

Return to top

Lessons

lesson.search

Searches for matching lessons in Dojo.

Parameters:

• query – The search query.

Example request:

GET /rest-action/lesson.search?user=USERID&apikey=APIKEY&query=keywords HTTP/1.1
Host: api.dojolearning.com

Successful response:

HTTP/1.1 200 OK

{
	"query": "keywords",
	"total": 2,
	"lessons": [
		{
			"id": 1,
			"url": "http://www.dojolearning.com/course-action/id.1",
			"title": "Example Lesson 1",
			"icon": "http://www.dojolearning.com/inc/app/dojo/pix/thumbnails/1-24x24.jpg"
		},
		{
			"id": 2,
			"url": "http://www.dojolearning.com/course-action/id.2",
			"title": "Example Lesson 2",
			"icon": "http://www.dojolearning.com/inc/app/dojo/pix/thumbnails/2-24x24.jpg"
		}
	]
}

Return to top

lesson.topics

Provides a list of topic categories in Dojo.

Example request:

GET /rest-action/lesson.topics?user=USERID&apikey=APIKEY HTTP/1.1
Host: api.dojolearning.com

Successful response:

HTTP/1.1 200 OK

[
	{
		"id": 1,
		"name": "Arts & Crafts"
	},
	{
		"id": 2,
		"name": "Communication"
	}
]

Return to top

lesson.list

Provides a list of lessons under the specified topic.

Parameters:

• topic – The topic ID to return lessons from.
• offset – The number of results to offset by. Start at 0 to get the first items.

Example request:

GET /rest-action/lesson.list?user=USERID&apikey=APIKEY&topic=1&offset=0 HTTP/1.1
Host: api.dojolearning.com

Successful response:

HTTP/1.1 200 OK

[
	{
		"id": 1,
		"url": "http://www.dojolearning.com/course-action/id.1",
		"title": "Example Lesson 1"
	},
	{
		"id": 2,
		"url": "http://www.dojolearning.com/course-action/id.2",
		"title": "Example Lesson 2"
	}
]

Return to top

lesson.newest

Provides a list of the 10 newest lessons on Dojo.

Example request:

GET /rest-action/lesson.newest?user=USERID&apikey=APIKEY HTTP/1.1
Host: api.dojolearning.com

Successful response:

HTTP/1.1 200 OK

[
	{
		"id": 2,
		"url": "http://www.dojolearning.com/course-action/id.2",
		"title": "Example Lesson 2"
	},
	{
		"id": 1,
		"url": "http://www.dojolearning.com/course-action/id.1",
		"title": "Example Lesson 1"
	}
]

Return to top

lesson.popular

Provides a list of the 10 most popular lessons on Dojo.

Example request:

GET /rest-action/lesson.popular?user=USERID&apikey=APIKEY HTTP/1.1
Host: api.dojolearning.com

Successful response:

HTTP/1.1 200 OK

[
	{
		"id": 1,
		"url": "http://www.dojolearning.com/course-action/id.1",
		"title": "Example Lesson 1"
	},
	{
		"id": 2,
		"url": "http://www.dojolearning.com/course-action/id.2",
		"title": "Example Lesson 2"
	}
]

Return to top

lesson.subscribed

Provides a list of the lessons you are signed up to.

Example request:

GET /rest-action/lesson.subscribed?user=USERID&apikey=APIKEY HTTP/1.1
Host: api.dojolearning.com

Successful response:

HTTP/1.1 200 OK

[
	{
		"id": 1,
		"url": "http://www.dojolearning.com/course-action/id.1",
		"title": "Example Lesson 1"
	}
]

Return to top

lesson.instructing

Provides a list of the lessons you are instructing.

Example request:

GET /rest-action/lesson.instructing?user=USERID&apikey=APIKEY HTTP/1.1
Host: api.dojolearning.com

Successful response:

HTTP/1.1 200 OK

[
	{
		"id": 2,
		"url": "http://www.dojolearning.com/course-action/id.2",
		"title": "Example Lesson 2"
	}
]

Return to top

lesson.summary

Provides a summary and module list for the specified lesson.

Parameters:

• id – The lesson ID.

Example request:

GET /rest-action/lesson.summary?user=USERID&apikey=APIKEY&id=1 HTTP/1.1
Host: api.dojolearning.com

Successful response:

HTTP/1.1 200 OK

{
	"id": 1,
	"owner": "USER",
	"title": "Example Lesson 1",
	"instructor: "USER",
	"language": "en",
	"topic": 1,
	"description": "Example lesson description...",
	"url": "http://www.dojolearning.com/course-action/id.1",
	"icon": "http://www.dojolearning.com/inc/app/dojo/pix/thumbnails/1-24x24.jpg",
	"chapters": [
		{
			"id": 1,
			"title": "Module one",
			"sample": "no",
			"objects": 4
		},
		{
			"id": 2,
			"title": "Module two",
			"sample": "no",
			"objects": 6
		}
	]
}

Return to top

lesson.chapter

Provides 10 objects from the specified module.

Parameters:

• id – The module ID.
• offset – The number of results to offset by. Start at 0 to get the first items.

Example request:

GET /rest-action/lesson.chapter?user=USERID&apikey=APIKEY&id=1&offset=0 HTTP/1.1
Host: api.dojolearning.com

Successful response:

HTTP/1.1 200 OK

[
	{
		"id": 1,
		"type": "text",
		"title": "Welcome to this lesson",
		"value": "This lesson will cover..."
	},
	{
		"id": 2,
		"type": "input-radio",
		"title": "How many legs does a spider have?",
		"options": [
			"Two"
			"Four",
			"Six",
			"Eight",
			"Ten"
		],
		"correct_answer": "Eight"
	},
	{
		"id": 3,
		"type": "video",
		"title": "Butterflies in Nature",
		"description": "A video about butterflies",
		"filesize": 21696242,
		"url": "http://www.dojolearning.com/file-action/name.1234.13243546.flv",
		"posterframe": "http://www.dojolearning.com/file-action/name.1234.13243546.jpg"
	}
]

The values available for each object depend on its type. The possible types are:

• audio
• checklist
• code
• definition
• file
• image
• input-checkbox
• input-file
• input-radio
• input-select
• input-text
• link
• map
• page-break
• rss
• snippet
• text
• video

The possible values returned are:

• correct_answer
• description
• filesize
• format
• id
• options
• posterframe
• title
• url
• value

Return to top

lesson.subscribe

Signs you to the specified lesson. Only free lessons can be subscribed through the API.

Parameters:

• id – The lesson ID.

Example request:

GET /rest-action/lesson.subscribe?user=USERID&apikey=APIKEY&id=1 HTTP/1.1
Host: api.dojolearning.com

Successful response:

HTTP/1.1 200 OK

true

Return to top

lesson.unsubscribe

Unsubscribes you from the specified lesson.

Parameters:

• id – The lesson ID.

Example request:

GET /rest-action/lesson.unsubscribe?user=USERID&apikey=APIKEY&id=1 HTTP/1.1
Host: api.dojolearning.com

Successful response:

HTTP/1.1 200 OK

true

Return to top

lesson.learners

Returns a list of users who are signed up to the specified lesson.

Parameters:

• id – The lesson ID.

Example request:

GET /rest-action/lesson.learners?user=USERID&apikey=APIKEY&id=1 HTTP/1.1
Host: api.dojolearning.com

Successful response:

HTTP/1.1 200 OK

[
	{
		"user_id": "bryanadams",
		"name": "Bryan Adams"
	},
	{
		"user_id": "philcollins",
		"name": "Phil Collins"
	},
	{
		"user_id": "steveperry",
		"name": "Steve Perry"
	}
]

Return to top

Journal

journal.list

Returns 10 journal entries from your journal, ordered from newest to oldest.

Parameters:

• offset – The number of results to offset by. Start at 0 to get the first items.

Example request:

GET /rest-action/journal.list?user=USERID&apikey=APIKEY&offset=0 HTTP/1.1
Host: api.dojolearning.com

Successful response:

HTTP/1.1 200 OK

{
	"total": 2,
	"entries": [
		{
			"id": 1,
			"user_id": "USER",
			"answer": "To be.",
			"filesize": 0,
			"viewed": "no",
			"question": "To be or not to be?",
			"lesson": 2,
			"object": 11,
			"posted": "2008-06-23 06:41:33",
			"replies": 2,
			"url": "http://www.dojolearning.com/journal-entry-action/id.1"
		},
		{
			"id": 2,
			"user_id": "USER",
			"answer": "real_filename.jpg",
			"filesize": 70454,
			"viewed": "yes",
			"question": "Upload a funny comic.",
			"lesson": 2,
			"object": 16,
			"posted": "2008-06-24 11:07:59",
			"replies": 0,
			"file": "http://www.dojolearning.com/file-action/name.j2.54321.jpg",
			"url": "http://www.dojolearning.com/journal-entry-action/id.2"
		}
	]
}

Return to top

journal.unread

Returns 10 unread journal entries from your journal, ordered from newest to oldest.

Parameters:

• offset – The number of results to offset by. Start at 0 to get the first items.

Example request:

GET /rest-action/journal.unread?user=USERID&apikey=APIKEY&offset=0 HTTP/1.1
Host: api.dojolearning.com

Successful response:

HTTP/1.1 200 OK

{
	"total": 1,
	"entries": [
		{
			"id": 1,
			"user_id": "USER",
			"answer": "To be.",
			"filesize": 0,
			"viewed": "no",
			"question": "To be or not to be?",
			"lesson": 2,
			"object": 11,
			"posted": "2008-06-23 06:41:33",
			"replies": 2,
			"url": "http://www.dojolearning.com/journal-entry-action/id.1"
		}
	]
}

Return to top

journal.entry

Returns the specified journal entry and its replies.

Parameters:

• id – Journal entry ID.

Example request:

GET /rest-action/journal.entry?user=USERID&apikey=APIKEY&id=1&offset=0 HTTP/1.1
Host: api.dojolearning.com

Successful response:

HTTP/1.1 200 OK

{
	"id": 1,
	"user_id": "USER",
	"lesson": 2,
	"chapter": 1,
	"object": 23,
	"posted": "2008-06-23 06:41:33",
	"question": "To be or not to be?",
	"answer": "To be.",
	"filesize": 0,
	"viewed": "no",
	"replies": [
		{
			"id": 1,
			"user_id": "USER",
			"posted": "2008-06-28 23:35:51",
			"reply": "Your reply",
			"filesize": 205288,
			"file": "http://www.dojolearning.com/file-action/name.f1.jpg"
		},
		{
			"id": 2,
			"user_id": "USER",
			"posted": "2008-06-29 06:17:42",
			"reply": "Another reply",
			"filesize": 0
		}
	]
}

Return to top

journal.reply

Creates a reply to the specified journal entry.

Parameters:

• id – Journal entry ID.
• reply – Your reply to the journal entry.

Example request:

POST /rest-action/journal.entry HTTP/1.1
Host: api.dojolearning.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 48

user=USERID&apikey=APIKEY&id=1&reply=Your+reply

Successful response:

HTTP/1.1 200 OK

{
	"id": 1,
	"entry_id": 1,
	"user_id": "USER",
	"posted": "2008-06-28 23:35:51",
	"reply": "Your reply"
}

Return to top

Lounge

lounge.topics

Returns a list of topics in the specified lounge.

Parameters:

• id – The lesson ID.

Example request:

GET /rest-action/lounge.topics?user=USERID&apikey=APIKEY&id=1 HTTP/1.1
Host: api.dojolearning.com

Successful response:

HTTP/1.1 200 OK

[
	{
		"id": 1,
		"name": "General",
		"summary": "General discussion",
		"url": "http://www.dojolearning.com/course-lounge-topic-action/id.1",
		"total": 2
	}
]

Return to top

lounge.threads

Returns a list of 10 threads in the specified lounge, sorted by newest to oldest.

Parameters:

• id – The lounge topic ID.
• offset – The number of results to offset by. Start at 0 to get the first items.

Example request:

GET /rest-action/lounge.threads?user=USERID&apikey=APIKEY&id=1 HTTP/1.1
Host: api.dojolearning.com

Successful response:

HTTP/1.1 200 OK

[
	{
		"id": 1,
		"subject": "Quick question",
		"body": "I'm wondering if anyone knows the answer to...",
		"posted": "2008-06-28 21:27:35",
		"updated": "2008-06-28 21:27:35",
		"user_id": "USER",
		"replies": 1,
		"url": "http://www.dojolearning.com/course-lounge-post-action/id.1"
	}
]

Return to top

lounge.thread

Returns the specified thread post and its replies.

Parameters:

• id – The lounge thread ID.

Example request:

GET /rest-action/lounge.thread?user=USERID&apikey=APIKEY&id=1 HTTP/1.1
Host: api.dojolearning.com

Successful response:

HTTP/1.1 200 OK

{
	"id": 1,
	"topic": 1,
	"subject": "Quick question",
	"body": "I'm wondering if anyone knows the answer to...",
	"posted": "2008-06-28 21:27:35",
	"updated": "2008-06-28 21:27:35",
	"user_id": "USER",
	"url": "http://www.dojolearning.com/course-lounge-post-action/id.1"
	"replies": [
		{
			"id": 4,
			"topic": 1,
			"subject": "Re: Quick question",
			"body": "Here, this might help...",
			"posted": "2008-06-30 18:46:21",
			"updated": "2008-06-30 18:46:21",
			"user_id": "USER",
			"url": "http://www.dojolearning.com/course-lounge-post-action/id.1#post-4"
		}
	],
}

Return to top

lounge.post

Creates a new thread post under the specified lounge topic.

Parameters:

• id – The lounge topic ID.
• subject – The subject of your new post.
• body – The body of your new post.

Example request:

POST /rest-action/lounge.post HTTP/1.1
Host: api.dojolearning.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 65

user=USERID&apikey=APIKEY&id=1&subject=SUBJECT&body=MESSAGE+BODY

Successful response:

HTTP/1.1 200 OK

{
	"id": 2,
	"topic": 1,
	"subject": "Another question",
	"body": "I'm wondering if anyone knows the answer to...",
	"posted": "2008-06-29 15:43:36",
	"updated": "2008-06-29 15:43:36",
	"user_id": "USER",
	"url": "http://www.dojolearning.com/course-lounge-post-action/id.2"
	"replies": []
}

Return to top

lounge.reply

Creates a reply to the specified post.

Parameters:

• id – The lounge post ID that the new post is in reply to.
• subject – The subject of your new post.
• body – The body of your new post.

Example request:

POST /rest-action/lounge.reply HTTP/1.1
Host: api.dojolearning.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 65

user=USERID&apikey=APIKEY&id=2&subject=SUBJECT&body=MESSAGE+BODY

Successful response:

HTTP/1.1 200 OK

{
	"id": 3,
	"topic": 1,
	"subject": "Re: Another question",
	"body": "Here's a good starting point for that...",
	"posted": "2008-06-29 20:12:54",
	"updated": "2008-06-29 20:12:54",
	"user_id": "USER",
	"url": "http://www.dojolearning.com/course-lounge-post-action/id.2#post-3"
}

Return to top

Notes

notes.get

Returns your notes for the specified lesson.

Parameters:

• id – The lesson ID.

Example request:

GET /rest-action/notes.get?user=USERID&apikey=APIKEY&id=1 HTTP/1.1
Host: api.dojolearning.com

Successful response:

HTTP/1.1 200 OK

"These are your notes."

Return to top

notes.save

Updates your notes for the specified lesson.

Parameters:

• id – The lesson ID.
• value – Your updated notes.

Example request:

POST /rest-action/notes.save HTTP/1.1
Host: api.dojolearning.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 51

user=USERID&apikey=APIKEY&id=1&value=Updated+notes

Successful response:

HTTP/1.1 200 OK

true

Return to top

People

person.profile

Gets the profile of the specified user.

Parameters:

• user_id – The specified user ID.

Example request:

GET /rest-action/person.profile?user=USERID&apikey=APIKEY&user_id=USER HTTP/1.1
Host: api.dojolearning.com

Successful response:

HTTP/1.1 200 OK

{
	"user_id": "bryanadams",
	"name": "Bryan Adams",
	"company": "Joe's Computers",
	"website": "http://www.example.com/",
	"about": "About me...",
	"state": "bc",
	"country": "ca",
	"language": "en",
	"avatar": "http://www.dojolearning.com/inc/app/dojo/pix/users/bryanadams.jpg"
}

Return to top

person.lessons

Returns a list of lessons created by the specified user.

Parameters:

• user_id – The specified user ID.

Example request:

GET /rest-action/person.lessons?user=USERID&apikey=APIKEY&user_id=USER HTTP/1.1
Host: api.dojolearning.com

Successful response:

HTTP/1.1 200 OK

[
	{
		"id": 1,
		"url": "http://www.dojolearning.com/course-action/id.1",
		"title": "Example Lesson 1"
	}
]

Return to top

person.subscribed

Returns a list of lessons the specified user is signed up to.

Parameters:

• user_id – The specified user ID.

Example request:

GET /rest-action/person.subscribed?user=USERID&apikey=APIKEY&user_id=USER HTTP/1.1
Host: api.dojolearning.com

Successful response:

HTTP/1.1 200 OK

[
	{
		"id": 2,
		"url": "http://www.dojolearning.com/course-action/id.2",
		"title": "Example Lesson 2"
	}
]

Return to top