Imagination For People

API reference (draft)

API Topology

API Interaction Format

Request parameters

Responses

Example

Projects

GET /api/v1/project/

Request parameters

Responses

Example

GET /api/v1/project/latest/

GET /api/v1/project/bestof/

Request parameters

Responses

GET /api/v1/project/by-country/{country_code}/

Request parameters

POST /api/v1/project/new

Request parameters

Example

Responses

Example:

POST /api/v1/project/update

GET /api/v1/project/{language_code}/{slug}/

GET /api/v1/project/random/

GET /api/v1/project/{project_id}/gallery/list.{format}

POST /api/v1/project/{project_id}/gallery/image.{format}

DELETE /api/v1/project/{id}/gallery/image.{format}

POST /api/v1/project/{project_id}/gallery/video

DELETE /api/v1/project/{project_id}/gallery/video/

POST /api/v1/project/{project_id}/refereces/list

CREATE /api/v1/project/{project_id}/references/new.{format}

DELETE /api/v1/project/{project_id}/references/{reference_id}.{format}

GET /api/v1/search/project/

Request parameters

GET /api/v1/workgroup/

GET /api/v1/workgroup/{slug}

Reference

Template

Request parameters

Responses

API Topology

Méthode

Route

Description

dispo

GET

/project

List of all projects
- filtered by recency/creation date
- filtered by lang
- ...

oui

GET

/project/latest

List of 40 latest projects ordered by descending creation date

oui

GET

/project/bestof

List of 80 best_of projects, ordered randomly

oui

GET

/project/by-country/{country_code}

List of projects that are declared inside a specific country

oui

POST

/project/new

Create a new project sheet

oui

UPDATE

/project/update

Update a given project sheet

GET

/project/{lang}/{slug}

Description of a project sheet translation
(selected by lang/slug)

oui

GET

/project/{id}

Description of a project sheet translation
(selected by id)

GET

/project/random

A random project

oui

GET

/search/project

List project matching some pattern

oui

GET

/workgroup

List of all groups

oui

GET

/workgroup/{slug}

Description of a group (selected by slug)

oui

GET

/user/{id}

Get info about some user

GET

/tags/list

List of all tags

CREATE

/tags/new

Add a new tag

API Interaction Format

Request parameters

Parameter

Type

Description

Default

Required

format

string “json”

Response format

N/A

yes

Responses

Meta field

Type

Description

status

unsigned integer

Return code is set according to request data and execution.

We follow the HTTP/FTP nomenclature :
1xx
→ information
2xx
→ success
3xx → redirection

4xx → user-related  error

5xx → server-related error

msg

string

A human readable text explaining the error.

Example

{
  "meta": {
     "status": 200,
     "msg": "OK",

  },
  "response": { ... }
}

Projects

GET /api/v1/project/

Request parameters

Parameter

Type

Description

Default

Required

limit

unsigned integer

Number of projects per page

20

no

offset

unsigned integer

Offset in the result list

0

no

Responses

Response field

Type

Description

token

string

user token

Meta field

Type

Description

previous

string or null

The link to the previous page of values matched by the request, with all request parameters sets.

next

string or null

The link to the next page of values matched by the request, with all request parameters sets.

total_count

unsigned integer

The total number of values matched by the request.

limit

unsigned integer

Number of projects in response

offset

unsigned integer

Offset in the response

Example

{

   "objects" : [

          {

             "resource_uri" : "/api/v1/project/854/",

             "baseline" : "An application that allows citizens to bring ...",

             "language_code" : "en",

             "project" : {

                "location" : null,

                "status" : "END",

                "pictures" : [

                   {

                      "thumb" : "http://.../thumbnail_api.png"

                   }

                ],

                "best_of" : true

             },

             "slug" : "fix-my-street",

             "title" : "Fix my street",

             "id" : 854

          },

          {

             "resource_uri" : "/api/v1/project/1/",

             "baseline" : "Application qui permet aux citoyens d'indiquer ...",

             "language_code" : "fr",

             "project" : {

                "location" : null,

                "status" : "END",

                "pictures" : [

                   {

                      "thumb" : "http://.../thumbnail_api.png"

                   }

                ],

                "best_of" : true

             },

             "slug" : "fix-my-street",

             "title" : "Fix my street",

             "id" : 1

          }

   ],

   "meta" : {

          "previous" : null,

          "next" : "/api/v1/project/?offset=2&limit=2&format=json",

          "limit" : 2,

          "total_count" : 2165,

          "offset" : 0

   }

}

GET /api/v1/project/latest/

GET /api/v1/project/bestof/

Request parameters

Parameter

Type

Description

Default

Required

Responses

Response field

Type

Description

Meta field

Type

Description

FIXME: we should add a limit  …

GET /api/v1/project/by-country/{country_code}/

Request parameters

Parameter

Type

Description

Default

Required

limit

int

Number of projects to return (can’t exceed 50)

50

no

POST /api/v1/project/new

Project creation sets creation date for the main project and modification dates on each translation.

Request parameters

Parameter

Type

Description

Default

Required

title

string

The title of the project

Yes

website

string

URL of the website of the project

empty

No

status

“IDEA” | ”CONCEPT” | ”WIP”
| “...”

Status of the project. To pick form STATUS_CHOICES

"IDEA"

No

lang

string

language code of the translation given

"en"

No

lang.{lang}

string[2]

No

Yes (at least one)

lang.{lang}.baseline

string

One line to describe the project

Yes

lang.*.about_section

string

Description of the project

empty

No

lang.*.innovation_section

string

Answer to the question: In which way this project is socially innovative?

empty

No

lang.*.themes

list of string

list of tags associated to the project

empty

No

Example

POST : http://imaginationforpeople.org/api/v1/project/new.json

+ Content-Type: application/json

{

   website : “lacoroutine.org”,

   status : WIP,

   lang : {

     en : {

        title : “The Coroutine”,

        baseline : “Espace de coopération pour passionnés”,

        about_section : “D’abord bureaux mutualisés, puis …”,

        innovation_section : “Cette initiative crée volontairement un …”,

        themes : “citoyens,coopération,coworking,développement, …”,

     },

     fr : {

        title : “La Coroutine”,

        baseline : “Espace de coopération pour passionnés”,

        about_section : “D’abord bureaux mutualisés, puis …”,

        innovation_section : “Cette initiative crée volontairement un …”,

       themes : “citoyens,coopération,coworking,développement économique, …”

    }

}

Responses

Response field

Type

Description

id

unsigned integer

id of the newly added project

lang.*.slug

string

slug of the project

lang.*.url

string

full URL of the newly added project

Example:

{
  "meta": {
     "status": 200,
     "msg": "New project successfully added",

  },
  "response": {

      “id” : 102,

      lang {

         “fr” : {

           "slug": "la-coroutine"

           "url": "http://../fr/project/la-coroutine"

         },

         “en” : {

           “slug”: ” the-coroutine”,

           "url": "http://../fr/project/la-coroutine"

         }

      },

   }
}

POST /api/v1/project/update

Project creation set modification date on each translation.

FIXME: complete here ;-)

GET /api/v1/project/{language_code}/{slug}/

GET /api/v1/project/random/

GET /api/v1/project/{project_id}/gallery/list.{format}

with alias as GET /api/v1/project/{lang}/{slug}/gallery/

FIXME: complete here ;-)

POST /api/v1/project/{project_id}/gallery/image.{format}

FIXME: complete here ;-)

DELETE /api/v1/project/{id}/gallery/image.{format}

or POST /api/v1/project/{id}/gallery/image/{image_id}/delete.{format}

FIXME: complete here ;-)

POST /api/v1/project/{project_id}/gallery/video

FIXME: complete here ;-)

DELETE /api/v1/project/{project_id}/gallery/video/

or POST /api/v1/project/{id}/gallery/image/{video_id}/delete

FIXME: complete here ;-)

POST /api/v1/project/{project_id}/refereces/list

FIXME: complete here ;-)

CREATE /api/v1/project/{project_id}/references/new.{format}

or POST /api/v1/project/{project_id}/references/new.json

FIXME: complete here ;-)

DELETE /api/v1/project/{project_id}/references/{reference_id}.{format}

or POST /api/v1/project/{project_id}/references/{reference_id}/delete.{format}

FIXME: complete here ;-)

GET /api/v1/search/project/

Request parameters

Parameter

Type

Description

Default

Required

lang

string

Code of search language

“en”

no

limit

int

Max number of results (can’t exceed 50)

50

no

q

string

Text to search

yes

GET /api/v1/workgroup/

GET /api/v1/workgroup/{slug}

Reference

Template

Request parameters

Parameter

Type

Description

Default

Required

Responses

Response field

Type

Description

Meta field

Type

Description