Skip to content

Projects API

Jump to bottom
amplifi edited this page Jun 29, 2017 · 1 revision

This document outlines the API design for organization projects. The concept is based on the projects [user flow] (https://drive.google.com/file/d/0BzpiEtMtHC3rM0RlaGt2UVFPMDA/view) and [project wireframes] (https://drive.google.com/file/d/0BzpiEtMtHC3reU94eGlrNmlialU/view) that the platform is going to support initially

API endpoints

List all projects for an organization.

Request

GET /organizations/{organisation-slug}/projects/
Accept: application/json
Content-Type: application/json
Authorization: Token 1398dojk9sd8jf9hsd89hd

Successful response

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": "0asjij9asjd8jh8ghashgd7",
        "name": "Region 3 Vineyards",
        "organization": "Habitat for Humanity",
        "country": "Uganda"
        "description: "The FAO, in collaboration with the Ministry, Kasese 
        District and the Makerere University, and with finacial support from 
        the UK Department for international development, has documented property
         rights using the OpenTenure tool, in order to issue Customary 
         Certificate of Occupancy",
        "logo": {
            "mime_type": "image/png",
            "url": "some/url/on/s3"
        },
        "archived": false,
        "urls": ["http://exmaple.com"],
        "contacts": [ // following http://microformats.org/wiki/h-card
            {
                "type": ["hcard"],
                "properties": {
                    "name": ["John Doe"],
                    "email": ["mailto:d.john@example.com"]
                }
            }
        ]
    },
    {
        "id": "0asjij9asjd8jh8ghashgd7",
        "name": "Mapping property rights in Colombia",
        "organization": "Habitat for Humanity",
        "country": "Kenya"
        "description: "Project to map property rights in Colombia",
        "logo": {
            "mime_type": "image/png",
            "url": "some/url/on/s3"
        },
        "archived": false,
        "urls": ["http://exmaple.com"],
        "contacts": [ // following http://microformats.org/wiki/h-card
            {
                "type": ["hcard"],
                "properties": {
                    "name": ["John Doe"],
                    "email": ["mailto:d.john@example.com"]
                }
            }
        ]
    },
]

Search

Providing a query for parameter search will return a list of projects where name, organization or description match the provided query.

GET /organizations/{organisation-slug}/projects/?search=habitat

Order

Orders the response according to name.

GET /organizations/{organisation-slug}/projects/?ordering=name

For descending ordering add add a dash to the ordering attribute

GET /organizations/{organisation-slug}/projects/?ordering=-name

Sample response

[
    {
        "id": "0asjij9asjd8jh8ghashgd7",
        "name": "Region 3 Vineyards",
        "organization": "Habitat for Humanity",
        "country": "Uganda"
        "description: "The FAO, in collaboration with the Ministry, Kasese 
        District and the Makerere University, and with finacial support from 
        the UK Department for international development, has documented property
         rights using the OpenTenure tool, in order to issue Customary 
         Certificate of Occupancy",
        "logo": {
            "mime_type": "image/png",
            "url": "some/url/on/s3"
        },
        "archived": false,
        "urls": ["http://exmaple.com"],
        "contacts": [ // following http://microformats.org/wiki/h-card
            {
                "type": ["hcard"],
                "properties": {
                    "name": ["John Doe"],
                    "email": ["mailto:d.john@example.com"]
                }
            }
        ]
    }
]

Errors

When the request content contains invalid data

HTTP/1.1 400 Bad request
Content-Type: application/json

{
  "name": "This field is required"
}

When the request is not signed with a auth token

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "Please sign in."
}

Create a new project for an organization.

Request

The request Content-Type must be multipart/formdata to allow uploading files together with other form data.

POST /organizations/{organisation-slug}/projects/
Content-Type: multipart/formdata
Authorization: Token 1398dojk9sd8jf9hsd89hd

---separator---
Content-Disposition: form-data; name="name"

Mapping land rights in Philippines
---separator---
Content-Disposition: form-data; name="description"

Recording property rights in the Philippines
---separator---
Content-Disposition: form-data; name="organization"

Habitat for Humanity
---separator---
Content-Disposition: form-data; name="country"

Philippines
---separator---
Content-Disposition: form-data; name="url"

http://www.habitat.org/
---separator---
Content-Disposition: form-data; name="logo"; filename="logo.png"
Content-Type: image/png

---separator---
Content-Disposition: form-data; name="contacts"
[ // following http://microformats.org/wiki/h-card
  {
    "type": ["hcard"],
    "properties": {
      "name": ["John Doe"],
      "email": ["mailto:d.john@example.com"]
    }
  }
]
---separator---

Successful response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "7etrtjkhgfd4567uhjgfe456h",
  "name": "Mapping land rights in Philippines",
  "country": "Philippines"
  "description: "Recording property rights in the Philippines",
  "logo": "some/url/on/s3",
  "archived": false,

  "contacts": [ // following http://microformats.org/wiki/h-card
    {
      "type": ["hcard"],
      "properties": {
        "name": ["Nicole Smith"],
        "email": ["mailto:n.smith@example.com"]
      }
    }
  ],
  "users": []
}

Get a single project

Request

GET /organizations/{organisation-slug}/projects/{project-slug}/
Accept: application/json
Content-Type: application/json
Authorization: Token 1398dojk9sd8jf9hsd89hd

Successful response

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": "0asjij9asjd8jh8ghashgd7",
        "name": "Region 3 Vineyards",
        "organization": "Habitat for Humanity",
        "country": "Uganda"
        "description: "The FAO, in collaboration with the Ministry, Kasese 
        District and the Makerere University, and with finacial support from 
        the UK Department for international development, has documented property
         rights using the OpenTenure tool, in order to issue Customary 
         Certificate of Occupancy",
        "logo": {
            "mime_type": "image/png",
            "url": "some/url/on/s3"
        },
        "archived": false,
        "urls": ["http://exmaple.com"],
        "contacts": [ // following http://microformats.org/wiki/h-card
            {
                "type": ["hcard"],
                "properties": {
                    "name": ["John Doe"],
                    "email": ["mailto:d.john@example.com"]
                }
            }
        ]
    }
]

Errors

Project not found

HTTP/1.1 404 Not found
Content-Type: application/json
{
  "error": "Project does not exist"
}

List project users

Request
GET /organizations/{organisation-slug}/projects/{project-slug}
Authorization: Token 1398dojk9sd8jf9hsd89hd

Successful response

HTTP/1.1 200 OK

[
  {
    "username": "d_john,
    "first_name": "John",
    "last_name": "Doe",
    "email": "d.john@example.com",
    "email_verified": true
  }
]

Errors

When the request is not signed with a auth token

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "Please sign in."
}

When the user is not authorised to see project users

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "You are not allowed to access users of this project."
}

Project not found

HTTP/1.1 404 Not found
Content-Type: application/json
{
  "error": "Project does not exist"
}

For security reasons, the existence of entities should not be revealed when the user does not have permissions to access the entity, hence 404 Not found should be returned.

Add user to a project

Request

POST /organizations/{organisation-slug}/projects/{project-slug/}users/
Content-Type: application/json
Authorization: Token 1398dojk9sd8jf9hsd89hd

{ "username": "some-user" }

Successful response

HTTP/1.1 201 Created

Errors

When the request is not signed with a auth token

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "Please sign in."
}

When the user is not authorised to add users to a project

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "You are not allowed to add users to the project."
}

Project not found

HTTP/1.1 404 Not found
Content-Type: application/json
{
  "error": "Project does not exist"
}

For security reasons, the existence of entities should not be revealed when the user does not have permissions to access the entity, hence 404 Not found should be returned.

Delete user from a project

Request

DELETE /organizations/{organisation-slug}/projects/{project-slug}/users/{username}/
Authorization: Token 1398dojk9sd8jf9hsd89hd

Successful response

HTTP/1.1 204 No Content

Errors

When the request is not signed with a auth token

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "Please sign in."
}

When the user is not authorised to remove users from the project

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "You are not allowed to remove users from the project."
}

Project not found

HTTP/1.1 404 Not found
Content-Type: application/json
{
  "error": "Project does not exist"
}

For security reasons, the existence of entities should not be revealed when the user does not have permissions to access the entity, hence 404 Not found should be returned.

Visit our User Documentation to learn more about using the Cadasta Platform.

If you'd like to contribute to the Cadasta Platform, start with our Contributing Guidelines.

Cadasta Wiki Home | Developer Setup Guide

Cadasta.org | About Cadasta | YouTube | Twitter | Facebook

Development

Design

Documentation Needs

  • Quick Start Guide
  • Glossary
  • Questionnaire Guide
Clone this wiki locally