API development process

work in progress, all help really welcome!

P2PU API

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.

Technology

tastypie will be used for the read only API.

Where to find the code?

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 review, it will be merged with the main Lernanta codebase but details are TBD.

Public calls

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?)

Working on

Right now we are working to expose the following information

Discussion

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.

links to forum threads with requests

add links here

• http://lists.p2pu.org/pipermail/p2pu-dev/2011-May/001195.html