Skip to content

Spatial units API

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

This document outlines the API design for organization project spatial units. The concept is based on the projects user flow and project-records wireframes that the platform is going to support initially

API endpoints

List all spatial units for a project.

Request

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

Successful response

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

[
    {
        "type": "Feature",
        "geometry": {
            "type": "Polygon",
            "coordinates": [
                [
                    [
                        -245.39088249206543,
                        -3.333262692430284
                    ],
                    [
                        -245.39021730422974,
                        -3.3330699000753414
                    ],
                    [
                        -245.39001345634458,
                        -3.334312339033184
                    ],
                    [
                        -245.39063572883606,
                        -3.334580105844384
                    ],
                    [
                        -245.39088249206543,
                        -3.333262692430284
                    ]
                ]
            ]
        },
        "properties": {
            "attributes": {},
            "id": "xicyfjpikxid5uk4xrex8tn4",
            "name": "Apartment Unit #5 (Test)",
            "relationships": [
                "8jp8gv4r958ppd695nauaeze"
            ],
            "type": "PA"
        }
    },
    {
        "type": "Feature",
        "geometry": {
            "type": "Point",
            "coordinates": [
                -245.39034605026242,
                -3.333294824485769
            ]
        },
        "properties": {
            "attributes": {
                "address": "102 Sesame St"
            },
            "id": "8jp8gv4r958ppd695nauaeze",
            "name": "Apartment Building 102 (Test)",
            "relationships": [],
            "type": "PA"
        }
    }
]

Search

Providing a query for parameter search will return a list of spatial units where name, relationship or related parties match the provided query.

GET /organizations/{organization-slug}/projects/{project-slug}/spatial/?search=apartment

Filter by type

Providing a query for parameter type will return a list of spatial units that match the given spatial unit type.

GET /organizations/{organization-slug}/projects/{project-slug}/spatial/?type=PA

Order

Orders the response according to name.

GET /organizations/{organization-slug}/projects/{project-slug}/spatial/?ordering=name

For descending ordering add add a dash to the ordering attribute

GET /organizations/{organization-slug}/projects/{project-slug}/spatial/?ordering=-name

Sample response

[
    {
        "type": "Feature",
        "geometry": {
            "type": "Polygon",
            "coordinates": [
                [
                    [
                        -245.39200901985168,
                        -3.333808937230755
                    ],
                    [
                        -245.39147257804868,
                        -3.3335304595272377
                    ],
                    [
                        -245.391343832016,
                        -3.3340338614721934
                    ],
                    [
                        -245.39186954498288,
                        -3.3342480749876575
                    ],
                    [
                        -245.39200901985168,
                        -3.333808937230755
                    ]
                ]
            ]
        },
        "properties": {
            "attributes": {
                "testing": "attributes"
            },
            "id": "yexbhspgtk2nhz5szvm9c7nv",
            "name": "Apartment Unit #5",
            "relationships": [],
            "type": "AP"
        }
    },
    {
        "type": "Feature",
        "geometry": {
            "type": "Polygon",
            "coordinates": [
                [
                    [
                        -245.3920519351959,
                        -3.3337982265513184
                    ],
                    [
                        -245.39097905158997,
                        -3.333284113800722
                    ],
                    [
                        -245.39072155952454,
                        -3.3345908165153215
                    ],
                    [
                        -245.39169788360596,
                        -3.3351691925723728
                    ],
                    [
                        -245.3920519351959,
                        -3.3337982265513184
                    ]
                ]
            ]
        },
        "properties": {
            "attributes": {},
            "id": "uaxwi255asr6ybb6mq76duy7",
            "name": "Building Unit #2B",
            "relationships": [
                "yexbhspgtk2nhz5szvm9c7nv"
            ],
            "type": "BU"
        }
    }
]

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

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

When the user is not authorized to view spatial units from a project

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

{
  "error": "You don't have permission to view spatial units in this project."
}

Create a new spatial unit for a project.

Request

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


{
    "type": "Feature",
    "geometry": {
        //following http://geojson.org/geojson-spec.html#appendix-a-geometry-examples
        "type": "Point",
        "coordinates": [100.0, 0.0]
    },
    "properties": {
        "name": "Apartment Building #102",
        "type": "Building",
        "attributes": {
            "address": "102 Sesame St"
        }
    }
}

Successful response

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

{
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [100.0, 0.0]
    },
    "properties": {
        "attributes": {
            "address": "102 Sesame St"
        },
        "id": "2nigat6sjt3ujic8mxc9h6n9",
        "name": "Apartment Building #102",
        "project": {
            "id": "hyw5fnhhxvsxwwtbqq67md6m",
            "name": "Mapping Sesame Street",
            "organization": {
                "id": "jv3spjy64i5asaqsh9xibeth",
                "name": "PBS",
                "slug": "pbs",
            },
            "slug": "mapping-sesame-street",
        },
        "relationships": [],
        "type": "PA"
    }
}

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

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

When the user is not authorized to add spatial units to a project

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

{
  "error": "You don't have permission to add spatial units to this project."
}

Get a single spatial unit

Request

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

Successful response

{
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [
            -245.39366126060483,
            -3.334130257559935
        ]
    },
    "properties": {
        "attributes": {},
        "id": "ddubxstqan2tvpb98vkkw8fh",
        "name": "Community Park",
        "project": {
            "id": "hyw5fnhhxvsxwwtbqq67md6m",
            "name": "Russellville Community Centers",
            "organization": {
                "id": "jv3spjy64i5asaqsh9xibeth",
                "name": "Cadasta",
                "slug": "cadasta"
            },
            "slug": "russellville-community-centers"
        },
        "relationships": [],
        "type": "MI"
    }
}

Errors

When the request is not signed with a auth token

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

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

When the user is not authorized to view spatial unit details

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

{
  "error": "You don't have permission to access this spatial unit."
}

Spatial unit not found.

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

{
  "detail": "SpatialUnit not found"
}

Update a spatial unit

Request

PATCH /organizations/{organization-slug}/projects/{project-slug}/spatial/{spatial-id}
Content-Type: application/json
Authorization: Token 1398dojk9sd8jf9hsd89hd

{
    "properties": {
        "name": "Apartment Building #103",
        "attributes": {
            "address": "103 Sesame St"
        }
    }
}

Successful response

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

{
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [
            100.0,
            0.0
        ]
    },
    "properties": {
        "attributes": {
            "address": "103 Sesame St"
        },
        "id": "2nigat6sjt3ujic8mxc9h6n9",
        "name": "Apartment Building #103",
        "project": {
            "id": "hyw5fnhhxvsxwwtbqq67md6m",
            "name": "Mapping Sesame Street",
            "organization": {
                "id": "jv3spjy64i5asaqsh9xibeth",
                "name": "PBS",
                "slug": "pbs",
            },
            "slug": "mapping-sesame-street",
        },
        "relationships": [],
        "type": "PA"
    }
}

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

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

When the user is not authorized to edit spatial units from the project

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

{
  "error": "You don't have permission to edit spatial units of this project"
}

Spatial unit not found.

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

{
  "detail": "SpatialUnit not found"
}

Delete a single spatial unit

Request

DELETE /organizations/{organisation-slug}/projects/{project-slug}/spatial/{spatial-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 authorized to remove users from the project

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

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

Spatial unit not found

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