10. Organizations

All users can see all organizations, and admins can manipulate them.

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.

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

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"
}

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

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

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

10.6. Organization Membership

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.

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"]

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.