Tenants
This section describes behavior of the Tenants object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from MWS.
The Fields: Tenants reference contains the type and description of all fields in the Tenants object.
Supported methods
| Resource | GET | PUT | POST | DELETE |
|---|---|---|---|---|
| /rest/tenants | Get All Tenants | -- | Create Single Tenant | -- |
| /rest/tenants/<id> | Get Single Tenant | Modify Single Tenant | -- | Delete Single Tenant |
| /rest/tenants/<name> | Get Single Tenant | Modify Single Tenant | -- | Delete Single Tenant |
| /rest/tenants/users/<username> | Get a User's Tenants | -- | -- | -- |
This topic contains these sections:
The HTTP GET method is used to retrieve Tenant information. You can query all tenants or a single tenant.
Quick reference
GET http://localhost:8080/mws/rest/tenants?api-version=3[&query={“field”:”value”}&sort={“field”:<1|-1>}] GET http://localhost:8080/mws/rest/tenants/<id>?api-version=3 GET http://localhost:8080/mws/rest/tenants/<name>?api-version=3
URLs and parameters
GET http://localhost:8080/mws/rest/tenants?api-version=3[&query={“field”:”value”}&sort={“field”:<1|-1>}]
| Parameter | Required | Type | Description | Example |
|---|---|---|---|---|
| query | No | JSON | Filter results. It is possible to query tenants by one or more fields based on MongoDB query syntax. | query={“name”:”TenantX”} |
| sort | No | JSON | Sort the results by field. Use 1 for ascending and -1 for descending. | sort={“name”:-1} |
See Global URL Parameters for available URL parameters.
Sample response
GET http://localhost:8080/mws/rest/tenants?api-version=3&field=name,description
-----------------------------
{
"totalCount": 2,
"resultCount": 2,
"results": [
{
"description": "Research personnel",
"name": "ResearchDept"
},
{
"description": "Programmers, testers, and product owners",
"name": "DevDept"
}
]
}
Sorting and querying
See the sorting and querying sections of Global URL Parameters.
URLs and parameters
GET http://localhost:8080/mws/rest/tenants/<id>?api-version=3 GET http://localhost:8080/mws/rest/tenants/<name>?api-version=3
| Parameter | Required | Type | Valid values | Description |
|---|---|---|---|---|
| id | Yes | String | -- | The unique identifier of the tenant. |
| name | Yes | String | -- | The name of the tenant. |
You must specify either id or name; you do not have to specify both.
See Global URL Parameters for available URL parameters.
Sample response
GET http://localhost:8080/mws/rest/tenants/ResearchDept?api-version=3
--------------------------
{
"attachedNodes": [
"node01",
"node02",
"node43"
],
"attachedPrincipals": [
{
"attachedRoles": [
{
"description": "",
"id": "51cb4e2b84ae4c8a68298268",
"name": "User",
"permissions": [
{
"action": "read",
"description": "",
"fieldPath": "*",
"id": "51cb4dca84ae4c8a68298226",
"label": "Read nodes",
"resource": "nodes",
"resourceFilter": null,
"type": "domain",
"version": 0
}
],
"version": 0
}
],
"description": "Research assistants, users, etc.",
"groups": [
{
"name": "cn=Engineering,ou=groups,dc=testldap,dc=ac",
"type": "LDAPGROUP"
}
],
"id": "51cb4c3b84ae4c8a6829812d",
"name": "Research",
"users": [ ],
"version": 1
}
],
"description": "Research personnel",
"id": "51ca256f84ae4c8a6828f8e9",
"name": "ResearchDept",
"version": 0
}
URLs and parameters
GET http://localhost:8080/mws/rest/tenants/users/<username>/<resource>/<action>?api-version=3
| Parameter | Required | Type | Valid values | Description |
|---|---|---|---|---|
| username | No | String | -- | User's user name. |
| resource | No | String | Any resource a user has permission for and that is assigned to a tenant. | An MWS resource. |
| action | No | String | create, read, update, delete | CRUD |
See Global URL Parameters for available URL parameters.
If username is unspecified, the current user's tenants are listed; if the user is not an RBAC user, all tenants are listed.
Sample response
GET http://localhost:8080/mws/rest/tenants/users/msmith?api-version=3
--------------------------
{
"totalCount": 2,
"resultCount": 2,
"results": [
{
"id": "51ffd9b1e4b027c0f94e65cf",
"name": "ResearchDiv"
},
{
"id": "51abcdef12345fedcba99978",
"name": "ResearchFaculty"
}
]
}
The HTTP POST method is used to submit Tenants.
Quick reference
POST http://localhost:8080/mws/tenants?api-version=3
URLs and parameters
POST http://localhost:8080/mws/tenants?api-version=3
See Global URL Parameters for available URL parameters.
Request body
The name field is required and must contain only letters, digits, periods, dashes, and underscores.
The attachedPrincipals field expects an array of tenant IDs or names.
The attachedNodes field expects an array of node IDs (api-version 1) or names (api-version 2).
The following is an example request body to create a tenant:
POST http://localhost:8080/mws/rest/tenants?api-version=3
----------------------------
{
"name": "ResearchDept",
"description": "Research personnel, assistants, and admins",
"attachedPrincipals": [
{"name": "ResearchAdmin"},
{"name": "ResearchLeader"},
{"name": "Research"}
],
"attachedNodes": [
"node01",
"node02",
"node43"
]
}
Sample response
If the request was successful, the response body is the new tenant, exactly as shown in Get Single Tenant. On failure, the response is an error message.
The HTTP PUT method is used to modify Tenants.
Quick reference
PUT http://localhost:8080/mws/rest/tenants/<id>?api-version=3 PUT http://localhost:8080/mws/rest/tenants/<name>?api-version=3
The HTTP PUT method is used to modify tenants.
URLs and parameters
PUT http://localhost:8080/mws/rest/tenants/<id>?api-version=3 PUT http://localhost:8080/mws/rest/tenants/<name>?api-version=3
| Parameter | Required | Type | Valid values | Description |
|---|---|---|---|---|
| id | Yes | String | -- | The unique identifier of the tenant. |
| name | Yes | String | -- |
The name of the tenant.
The name field must contain only letters, digits, periods, dashes, and underscores. |
| change-mode | Yes | String |
add remove set (default) |
If add, add the given objects (attachedNodes, attachedPrincipals) to the objects that already exist. If remove, delete the given objects from the objects that already exist. If set, replace existing objects with those specified |
You must specify either id or name; you do not have to specify both.
The attachedPrincipals field expects an array of tenant IDs or names.
The attachedNodes field expects an array of node IDs (api-version 1) or names (api-version 2).
See Global URL Parameters for available URL parameters.
Example request
PUT http://localhost:8080/mws/rest/tenants/ResearchDept?api-version=3
--------------------------------
{
attachedNodes: [
"node01",
"node03",
"node43",
"node44"
],
attachedPrincipals: [
{name: "ResearchAdmin"},
{name: "ResearchLeader"},
{name: "Research"}
]
}
The version field contains the current version of the database entry. This field cannot be updated directly. However, if version is included in the modify request, it will be used to verify that another client did not update the object between the time that the data was retrieved and the modify request was delivered.
Sample response
If the request was successful, the response body is the modified tenant as shown in Get Single Tenant. On failure, the response is an error message.
The HTTP DELETE method is used to delete tenants.
Quick reference
DELETE http://localhost:8080/mws/rest/tenants/<id>?api-version=3 DELETE http://localhost:8080/mws/rest/tenants/<name>?api-version=3
URLs and parameters
DELETE http://localhost:8080/mws/rest/tenants/<id>?api-version=3 DELETE http://localhost:8080/mws/rest/tenants/<name>?api-version=3
| Parameter | Required | Type | Valid values | Description |
|---|---|---|---|---|
| id | Yes | String | -- | The unique identifier of the tenant. |
| name | Yes | String | -- | The name of the tenant. |
You must specify either id or name; you do not have to specify both.
See Global URL Parameters for available URL parameters.
Sample response
JSON response
--------------------------------
{}
Related Topics