Organizations API

API endpoints

List all organisations

Request

GET /organizations/
Accept: application/json
Content-Type: application/json
Authorization: Token 1398dojk9sd8jf9hsd89hd

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

Filter

GET /organizations/?active=true

Returns all active organisations.

Search

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

GET /organizations/?search=habitat

Order

Orders the response according to name.

GET /organizations/?ordering=name

For descending ordering add add a dash to the ordering attribute

GET /organizations/?ordering=-name

Successful response

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

[
  {
    "id": "0asjij9asjd8jh8ghashgd7",
    "name": "Habitat for Humanity",
    "description: "Habitat for Humanity is a nonprofit, ecumenical Christian housing organization. It seeks to eliminate poverty housing and homelessness from the world, and to make decent shelter a matter of conscience and action. ",
    "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": ["Nicole Smith"],
           "email": ["mailto:[email protected]"]
         }
      }
    ]
  }
]

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

Create a new organization

Request

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

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

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

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

Habitat for Humanity is a nonprofit...
---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": ["Nicole Smith"],
      "email": ["mailto:[email protected]"]
    }
  }
]
---separator---

Successful response

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

{
  "id": "0asjij9asjd8jh8ghashgd7",
  "name": "Habitat for Humanity",
  "description: "Habitat for Humanity is a nonprofit, ecumenical Christian housing organization. It seeks to eliminate poverty housing and homelessness from the world, and to make decent shelter a matter of conscience and action. ",
  "logo": "some/url/on/s3",
  "archived": false,

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

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 organisations

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

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

Get a single organisation

Request

GET /organizations/{organisation-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": "Habitat for Humanity",
  "description: "Habitat for Humanity is a nonprofit, ecumenical Christian housing organization. It seeks to eliminate poverty housing and homelessness from the world, and to make decent shelter a matter of conscience and action. ",
  "logo": {
    "mime_type": "image/png",
    "url": "some/url/on/s3"
  }
  "archived": false,
  "contacts": [ // following http://microformats.org/wiki/h-card
    {
      "type": ["hcard"],
      "properties": {
        "name": ["Nicole Smith"],
        "email": ["mailto:[email protected]"]
      }
    }
  ],
  "users": []
}

Errors

Organization not found

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

Update an organisation

Request

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

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

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

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

Habitat for Humanity is a nonprofit...
---separator---
Content-Disposition: form-data; name="logo"; filename="logo.png"
Content-Type: image/png

---separator---
Content-Disposition: form-data; name="contacts"
[
  {
    "type": ["hcard"],
    "properties": {
      "name": ["Nicole Smith"],
      "email": ["mailto:[email protected]"]
    }
  }
]
---separator---

Successful response

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

{
  "id": "0asjij9asjd8jh8ghashgd7",
  "name": "Habitat for Humanity",
  "description: "Habitat for Humanity is a nonprofit, ecumenical Christian housing organization. It seeks to eliminate poverty housing and homelessness from the world, and to make decent shelter a matter of conscience and action. ",
  "logo": "some/url/on/s3",
  "archived": false,

  "contacts": [ // following http://microformats.org/wiki/h-card
    {
      "type": ["hcard"],
      "properties": {
        "name": ["Nicole Smith"],
        "email": ["mailto:[email protected]"]
      }
    }
  ]
}

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 organisation

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

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

Organization not found

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

Request

DELETE /organizations/{organisation-slug}/
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 organisation

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

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

Organization not found

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

List organisation users

Request

GET /organizations/{organisation-slug}/users/
Authorization: Token 1398dojk9sd8jf9hsd89hd

Successful response

HTTP/1.1 200 OK

[
  {
    "username": "p_smith,
    "first_name": "Prudence",
    "last_name": "Smith",
    "email": "[email protected]",
    "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 organization users

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

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

Organization not found

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

Request

POST /organizations/{organisation-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 an organization

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

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

Organization not found

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

Request

DELETE /organizations/{organisation-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 organization

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

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

Organization not found

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