-
Notifications
You must be signed in to change notification settings - Fork 64
API development process
The development of an API has been requested in several occasions by the community. With this page we are starting a process to create a read only API that will expose some of the information to the public through a REST-style architecture.
This page can be used for discussion on the features and collaboration.
tastypie will be used to create a REST-style read only API on top of the existing Lernanta functionality.
This is a community contributed project and the original code can be found at:
https://github.com/josmas/lernanta/tree/api
The code to this date (July 2012) has been merged into the master Lernanta branch, but there it has not been fully tested or deployed yet.
There is a demo of this code at: http://alpha.p2pu.org:8094/api/v1/?format=json
(note that in the newer code the version name has been changed from 'v1' to 'alpha')
The API related code is being developed in an additional Django app located in apps/api/*.
To get the code working you just need to fork the original repo (make sure you checkout the api branch) or the master Lernanta branch, and get your development environment working by following these instructions for a local Django install or use this Vagrant instructions to install a virtual machine.
The api is served in a subdomain, and to get that working you will need to add the following entry to your hosts file (generally located in /etc/hosts):
127.0.0.1 api.localhost
This is all you need to work with the API as it is part of the overall system, and will be available after getting your server up and running and your local redirect to api.localhost.
The main changes can be seen in this commit. As you can see there, some requirements have been added to the prod.txt file, the new api app along with tastypie have been added to the settings.py file, and finally a url matcher was added to the main urls.py file.
The code for the API itself is contained in the file apps/api/api.py and it is supposed to keep on evolving with time and requirements.
Most of the discussion is happening in the mailing list and we are also keeping tasks and assignments in this trello board.
All the public calls can be seen by calling the following URL from a browser:
http://api.localhost:8000/alpha/?format=json
The ?format=json attribute is only needed if you are looking at the API from a browser. From any device that can state the format of the expected output you won't need this attribute. For instance from curl it will default to JSON but you can change it with:
curl -H "Accept: application/json" http://api.localhost:8000/alpha/
The public routes as of now (March 2012) are the following:
{
badge: {
list_endpoint: "/alpha/badge/",
schema: "/alpha/badge/schema/"
},
project: {
list_endpoint: "/alpha/project/",
schema: "/alpha/project/schema/"
},
school: {
list_endpoint: "/alpha/school/",
schema: "/alpha/school/schema/"
},
users: {
list_endpoint: "/alpha/users/",
schema: "/alpha/users/schema/"
}
}
This means that to get 20 badges (20 is the default limit) you can ask for:
http://api.localhost:8000/alpha/badge/?format=json
And to get the badge with id 1 you would ask for:
http://api.localhost:8000/alpha/badge/1/?format=json
In more detail the calls above are:
- /project - expose courses/challenges/study-groups hosted on p2pu (name, descriptions, state, dates, duration, school, ...)
- /project/[id] - get full details for a specific project by id
Sample output:
{
category: "challenge",
community_featured: false,
completion_badges: [
"/alpha/badge/1/",
"/alpha/badge/8/",
"/alpha/badge/9/",
"/alpha/badge/10/"
],
created_on: "2011-10-13T02:01:34",
duration_hours: 0,
end_date: null,
featured: false,
image: null,
language: "en",
long_description: "<p>test</p>",
name: "Test Webmaking 101 - Challenge 1",
other: "",
other_description: "",
resource_uri: "/alpha/project/1/",
school: "/alpha/school/3/",
short_description: "test",
slug: "test-webmaking-101",
start_date: null
}
Note how you can navigate to associated data such as challenges or school from a particular project.
The following routes are also available (no samples given):
-
/userprofile - expose a list of users
- /userprofile/[id] - get full user details by id
-
/badge - get a list of badges from p2pu
- /badge/[id] - get full details for a specific badge by id
-
/school - get a list of Shcools with their details from p2pu
- /school/[id] - get full details for a specific School by id (would make more sense by name?)
If you want some information to be exposed feel free to add to a list in here.
NOTE: Is it useful to expose a /tasks endpoint right now? Shouldn't a group (in it's current form return the nested set of tasks that are in the group?
- /tasks - expose the content of courses (name of tasks, content of tasks) which could be useful for things related to compiling the content of courses into books or other formats appropriate for different audiences.
add links here