Skip to content

Latest commit

 

History

History
327 lines (223 loc) · 6.74 KB

api_orgs.rst

File metadata and controls

327 lines (223 loc) · 6.74 KB
Raw

Organizations

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

Organization Query

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 :wotkit-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.

Viewing a Single Organization

To view a single organization, query by name:

URL :wotkit-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 ":wotkit-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"
}

Organization Creation

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 :wotkit-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.

Organization Updating

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 :wotkit-api-v1:orgs/{org-name}
Privacy Admin
Format json
Method PUT
Returns 200 OK if successful. No content on body.

Organization Deletion

Deleting an Organization

Deleting an organization is done by deleting the organization resource.

To delete a user:

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

Organization Membership ---------------------

Organization Members

List all members of an Organization

To query for organization members:

URL :wotkit-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.

Organization Member Creation

Add new members to an Organization

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

URL :wotkit-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 ':wotkit-api-v1:orgs/electric-inc/members'

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

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

Organization Member Removal

Remove members from an Organization

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

URL :wotkit-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.