2.10. Organizations¶
All users can see all organizations, and admins can manipulate them.
2.10.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/orgs?{query} |
Privacy | Public |
Format | json |
Method | GET |
Returns | On error, an appropriate HTTP status code; On success, OK 200 and a list of organizations matching the query from newest to oldest. |
2.10.2. Viewing a Single Organization¶
To view a single organization, query by name:
URL | http://wotkit.sensetecnic.com/api/orgs/{org-name} |
Privacy | Public |
Format | json |
Method | GET |
Returns | Appropriate HTTP status code; OK 200 - if successful |
example
curl "http://wotkit.sensetecnic.com/api/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.10.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.
- The “name” and “longName” fields are required and must both be at least 4 characters long.
- The “imageUrl” and “description” fields are optional.
To create an organization:
URL | http://wotkit.sensetecnic.com/api/orgs |
Privacy | Admin |
Format | json |
Method | POST |
Returns | HTTP status code; Created 201 if successful; Bad Request 400 if organization is invalid; Conflict 409 if an organization with the same name already exists |
2.10.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/orgs/{org-name} |
Privacy | Admin |
Format | json |
Method | PUT |
Returns | HTTP status code; No Content 204 if successful |
2.10.5. Deleting an Organization¶
Deleting an organization is done by deleting the organization resource.
To delete a user:
URL | http://wotkit.sensetecnic.com/api/orgs/{org-name} |
Privacy | Admin |
Format | not applicable |
Method | DELETE |
Returns | HTTP status code; No Content 204 if successful |
2.10.6. Organization Membership¶
2.10.6.1. List all members of an Organization¶
To query for organization members:
URL | http://wotkit.sensetecnic.com/api/orgs/{org-name}/members |
Privacy | Admin |
Format | not applicable |
Method | GET |
Returns | On error, an appropriate HTTP status code; On success, OK 200 and a list of organization members. |
2.10.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/orgs/{org-name}/members |
Privacy | Admin |
Format | json |
Method | POST |
Returns | On error, an appropriate HTTP status code; On success, OK 204. |
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/orgs/electric-inc/members'
The file users-list.txt would contain the following.
["abe", "beth", "cecilia", "dylan"]
2.10.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/orgs/{org-name}/members |
Privacy | Admin |
Format | json |
Method | DELETE |
Returns | On error, an appropriate HTTP status code; On success, OK 204. |
Usernames that are not members, or usernames that do not exist, will be ignored.