-
Notifications
You must be signed in to change notification settings - Fork 64
API development process
work in progress, all help really welcome!
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 so for now the code related to the API is being kept at:
https://github.com/josmas/lernanta/tree/api
At some point, and after detailed review, it will be merged with the main Lernanta codebase but details are TBD.
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 repo (make sure you checkout the api branch) and get your development environment working by following these instructions.
Setting the dev environment 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.
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://localhost:8000/en/api/v1/?format=json
The ?format=json attribute is only needed if you are looking at the API from a browser. Other formats supported are xml and yaml. 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/xml" http://localhost:8000/api/v1/
The public routes as of now (March 2012) are the following:
{
badge: {
list_endpoint: "/en/api/v1/badge/",
schema: "/en/api/v1/badge/schema/"
},
project: {
list_endpoint: "/en/api/v1/project/",
schema: "/en/api/v1/project/schema/"
},
school: {
list_endpoint: "/en/api/v1/school/",
schema: "/en/api/v1/school/schema/"
},
userprofile: {
list_endpoint: "/en/api/v1/userprofile/",
schema: "/en/api/v1/userprofile/schema/"
}
}
This means that to get 20 badges (20 is the default limit) you can ask for:
http://localhost:8000/en/api/v1/badge/?format=json
And to get the badge with id 1 you would ask for:
http://localhost:8000/en/api/v1/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: [
"/en/api/v1/badge/1/",
"/en/api/v1/badge/8/",
"/en/api/v1/badge/9/",
"/en/api/v1/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: "/en/api/v1/project/1/",
school: "/en/api/v1/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?)
Right now we are working to expose the following information
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