Skip to content

Resources API

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

API endpoints

General

Retrieve resources

  • List all resources *
GET /resources/
Accept: application/json
Content-Type: application/json
Authorization: Token 1398dojk9sd8jf9hsd89hd

The requested list of resources can be filtered, searched and ordered by providing any combination of the following query parameters.

Filter

GET /resources/?active=true

Returns all active resources.

Search

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

GET /resources/?search=certificate

Order

Orders the response according to name.

GET /resources/?ordering=name

For descending ordering add add a dash to the ordering attribute

GET /resources/?ordering=-name

Get

Successful response

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

[
  {
    "id": "0asjij9asjd8jh8ghashgd7",
    "name": "Certificate of Ownership",
    "description": "This certificate shows ownership of the land parcel",
    "resource": "some/url/on/s3",
    "mime_type": "image/png",
    "archived": false,
    "attributes": {},
    "entity_type": "project",


  },
  {
    "id": "0asjij9asjd8jh8ghashgd7",
    "name": "Certificate of Freehold",
    "description": "This certificate shows ownership of the land parcel",
    "resource": "some/url/on/s3",
    "mime_type": "image/png",
    "archived": false,
    "attributes": {},
    "entity_type": "organization",

  },
]

If the user, who is authenticated with the request, is not authorized to view any resources, the response will return an empty array.

Unsupported operations

The following operations should be done at the entity specific API endpoint.

  • Put *
  • Delete *
  • Update *

Entity Specific

Create

Request

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

POST /resources/
Content-Type: multipart/formdata
Authorization: Token 1398dojk9sd8jf9hsd89hd

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

Certificate of Ownership
---separator---
Content-Disposition: form-data; name="description"

Certificate of Ownership
---separator---
Content-Disposition: form-data; name="resource"
Content-Type: image/png

"some/url/on/s3"

Successful response

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

{
    "id": "0asjij9asjd8jh8ghashgd7",
    "name": "Certificate of Tenure",
    "description": "This certificate shows ownership of the land parcel",
    "resource": "some/url/on/s3",
    "mime_type": "image/png",
    "archived": True,
    "attributes": {},
    "entity_type": "parcel",
}

List

Search

Update

List resources from Cadasta platform approved entities

A resource can be used by morning than one organization

List resources in an organization

Request

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

Successful response

HTTP/1.1 200 OK
Content-Type: application/json
[
{
    "id": "0asjij9asjd8jh8ghashgd7",
    "name": "Contract",
    "description": "Contract",
    "resource": "some/url/on/s3",
    "mime_type": "image/png",
    "archived": False,
    "attributes": {},
    "entity_type": "organization",
},
{
    "id": "lkv56768t7youhkgjv9o8u",
    "name": "Memorandum",
    "description": "Memorandum",
    "resource": "some/url/on/s3",
    "mime_type": "image/png",
    "archived": False,
    "attributes": {},
    "entity_type": "organization",
}
]
List resources in a project

Request

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

Successful response

HTTP/1.1 200 OK
Content-Type: application/json
[
{
    "id": "0asjij9asjd8jh8ghashgd7",
    "name": "Project Description",
    "description": "Project Description",
    "resource": "some/url/on/s3",
    "mime_type": "image/png",
    "archived": False,
    "attributes": {},
    "entity_type": "project",
},
{
    "id": "lkv56768t7youhkgjv9o8u",
    "name": "Memorandum",
    "description": "Memorandum",
    "resource": "some/url/on/s3",
    "mime_type": "image/png",
    "archived": False,
    "attributes": {},
    "entity_type": "project",
}
]

TODO:

==Party, Parcel, Tenure relationship entities to be added later==

Create a new resource

Resource can be created from/for a particulary entity type. The entity types are currently limited to:-

  • party
  • party_relationship
  • spatial_unit
  • spatial_unit_relationship
  • tenure_relationship
  • organization
  • project
  • questionnaire
  • question
Create a resource for an organization

Request

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

POST /resources/
Content-Type: multipart/formdata
Authorization: Token 1398dojk9sd8jf9hsd89hd

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

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

Contract
---separator---
Content-Disposition: form-data; name="resource"
Content-Type: image/png

"some/url/on/s3
---separator---

Successful response

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

{
    "id": "0asjij9asjd8jh8ghashgd7",
    "name": "Contract",
    "description": "Contract",
    "resource": "some/url/on/s3",
    "mime_type": "image/png",
    "archived": false,
    "attributes": {},
    "entity_type": "organization",
}

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."
}

When the user is not authorised to create resources

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

{
  "error": "You are not allowed to create new resources."
}

Get a single resource

Request

GET /resources/{resource-id}/
Accept: application/json
Content-Type: application/json
Authorization: Token 1398dojk9sd8jf9hsd89hd

Successful response

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

{
    "id": "0asjij9asjd8jh8ghashgd7",
    "name": "Certificate of Tenure",
    "description": "This certificate shows ownership of the land parcel",
    "resource": "some/url/on/s3",
    "mime_type": "image/png",
    "archived": false,
    "attributes": {},
    "entity_type": "parcel",
}

Update an resource

Request

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

PATCH /resources/{resource-id}/
Content-Type: multipart/formdata
Authorization: Token 1398dojk9sd8jf9hsd89hd

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

Certificate of Individual Ownership
---separator---
Content-Disposition: form-data; name="description"

Certificate of Individual Ownership
---separator---

Successful response

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

{
    "id": "0asjij9asjd8jh8ghashgd7",
    "name": "Certificate of Individual Ownership",
    "description": "Certificate of Individual Ownership",
    "resource": "some/url/on/s3",
    "mime_type": "image/png",
    "archived": false,
    "attributes": {},
    "entity_type": "parcel",
}

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."
}

When the user is not authorised to update the resource

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

{
  "error": "You are not allowed to update the resource."
}

Resource not found

HTTP/1.1 404 Not found
Content-Type: application/json
{
  "error": "Resource 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 an resource (not implemented in first version)

Request

DELETE /resources/{resource-id}/
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 delete the resource

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

{
  "error": "You are not allowed to delete the resource."
}

Resource not found

HTTP/1.1 404 Not found
Content-Type: application/json
{
  "error": "Resource 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