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. |
example
curl "http://wotkit.sensetecnic.com/api/v1/orgs/electric-inc"
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.