2.9. Organizations

Organizations allow multiple users to create and manage shared sensors. All users can see organizations, but only admins can manipulate them.

2.9.1. List/Query Organizations

A list of matching organizations may be queried by the system. The optional query parameters are as follows:

Name Value Description
text text to search for in the name, long name and/or description
offset offset into list of organizations for paging
limit limit to show for paging. The maximum number of organizations to display is 1000.

To query for organizations, add query parameters after the sensors URL as follows:

URL http://wotkit.sensetecnic.com/api/v1/orgs?{query}
Privacy Public
Format json
Method GET
Returns 200 OK on success. A JSON object in the response body containing a list of organizations matching the query from newest to oldest.

2.9.2. Viewing a Single Organization

To view a single organization, query by name:

URL http://wotkit.sensetecnic.com/api/v1/orgs/{org-name}
Privacy Public
Format json
Method GET
Returns 200 OK if successful and a JSON on body describing the organization.

Output:

{
        "id": 4764,
        "name": "electric-inc",
        "longName": "Electric, Inc.",
        "description": "Electric, Inc. was established in 1970.",
        "imageUrl": "http://www.example.com/electric-inc-logo.png"
}

2.9.3. Creating/Registering an Organization

To register a new organization, you POST an organization resource to the url /org. The organization resources is a JSON object with the following fields:

  • The organization resources is a JSON object.
  • The “name” and “longName” fields are required and must both be at least 4 characters long.
  • The “imageUrl” and “description” fields are optional.
  Field Name Information
(REQUIRED) name The name of the organization. Must be at least 4 characters long.
(REQUIRED) longName A descriptive name of the organization. Must be at least 4 characters long. Can be updated.
(OPTIONAL) description Description of the organization. Can be updated.
(OPTIONAL) imageUrl An image that often used in thumbnails to identify the organization. Can be updated.

To create an organization:

URL http://wotkit.sensetecnic.com/api/v1/orgs
Privacy Admin
Format json
Method POST
Returns 201 Created if successful; Bad Request 400 if organization is invalid; Conflict 409 if an organization with the same name already exists.

2.9.4. Updating an Organization

  • You may update any fields except “id” and “name”.
  • Only fields that are present in the JSON object will be updated.

To update an organization:

URL http://wotkit.sensetecnic.com/api/v1/orgs/{org-name}
Privacy Admin
Format json
Method PUT
Returns 200 OK if successful. No content on body.

2.9.5. Deleting an Organization

Deleting an organization is done by deleting the organization resource.

To delete a user:

URL http://wotkit.sensetecnic.com/api/v1/orgs/{org-name}
Privacy Admin
Format n/a
Method DELETE
Returns 200 OK if successful. No content on body.

2.9.6. Organization Membership

2.9.6.1. List all members of an Organization

To query for organization members:

URL http://wotkit.sensetecnic.com/api/v1/orgs/{org-name}/members
Privacy Admin
Format n/a
Method GET
Returns 200 OK on success. A JSON object in the response body containing a list of organization members.

2.9.6.2. Add new members to an Organization

To add new members to an organization, post a JSON array of usernames:

URL http://wotkit.sensetecnic.com/api/v1/orgs/{org-name}/members
Privacy Admin
Format json
Method POST
Returns 204 No Content on success.

Usernames that are already members, or usernames that do not exist, will be ignored.

For instance, to add the users “abe”, “beth”, “cecilia” and “dylan” to the organization “electric-inc”:

example

curl --user {id}:{password} --request POST
--header "Content-Type: application/json" --data-binary @users-list.txt
'http://wotkit.sensetecnic.com/api/v1/orgs/electric-inc/members'

The file users-list.txt would contain the following.

["abe", "beth", "cecilia", "dylan"]

2.9.6.3. Remove members from an Organization

To remove members from an organization, DELETE a JSON array of usernames:

URL http://wotkit.sensetecnic.com/api/v1/orgs/{org-name}/members
Privacy Admin
Format json
Method DELETE
Returns 204 No Content on success. A JSON object in the response body containing a list of usernames.

Usernames that are not members, or usernames that do not exist, will be ignored.