SMART COSMOS Edge User (DevKit) API Documentation
Authorities
Tenant Authorities
User Authorities
REST API
Endpoint |
REST API |
Required Authority |
|
none |
|
|
||
|
||
|
Endpoint |
REST API |
Required Authority |
|
||
|
||
|
||
|
||
|
Endpoint |
REST API |
Required Authority |
|
||
|
||
|
||
|
||
|
JSON Fields for Tenants
| Field | Format | Default | Required | Description |
|---|---|---|---|---|
|
String |
generated |
no |
representation of a User identifier in a common scheme, e.g. |
|
String |
no default |
yes |
Name of the tenant organization (e.g. |
|
boolean |
true |
no |
|
|
String |
no default |
yes (for create) |
Initial admin account |
JSON Fields for Users
| Field | Format | Default | Required | Description |
|---|---|---|---|---|
|
String |
generated |
no |
representation of a User identifier in a common scheme, e.g. |
|
String |
no default |
yes |
login name, e.g. |
|
String |
no default |
no |
e.g. |
|
boolean |
true |
no |
|
|
String |
no default |
no |
|
|
String |
no default |
no |
|
|
String |
no default |
no |
|
|
Array of String |
no default |
yes |
e.g. |
|
Array of String |
no default |
yes |
e.g. |
|
String |
no default |
yes |
representation of the tenant identifier in a common scheme, e.g. |
JSON Fields for Roles
| Field | Format | Default | Required | Description |
|---|---|---|---|---|
|
String |
generated |
no |
representation of a Role identifier in a common scheme, e.g. |
|
String |
no default |
yes |
Unique name of the role, e.g. |
|
Array of String |
no default |
yes |
e.g. |
|
String |
no default |
yes |
representation of the tenant identifier in a common scheme, e.g. |
Note that the illustrated scheme for URNs is only for documentation purposes. There must not be any assumptions or expectations on the scheme in the REST layer. All URNs or identifiers are just String values in the scope of REST modules!
Request parameters
| Parameter | Parameter Type | Format | Description |
|---|---|---|---|
|
url |
String |
the URN of the Tenant, User, or Role |
|
query |
String |
Optional search parameter to filter the search result by |
API Endpoints
| Response | Description |
|---|---|
400 BAD REQUEST |
There were constraint violations in the request body. |
401 UNAUTHORIZED |
The User represented by the authentication header could not be authenticated. |
403 FORBIDDEN |
The User represented by the authentication header lacks the authority to perform this action. |
404 NOT FOUND |
The Thing or Metadata was not found. |
409 CONFLICT |
A Thing with this URN already exists. |
Tenant Endpoints
Create - POST /tenants
Create a new Tenant, and a default User with the Admin Role.
POST /tenants
Example 1
{
"active": true,
"name": "Example Company",
"username": "waldo@example.com"
}201 CREATED
{
"urn": "urn:tenant:uuid:346e742e-2f1e-4d91-9ffe-7b38eec6219c",
"admin": {
"urn": "urn:user:uuid:34068f4d-12a5-4546-80f8-9f84b762db20",
"username": "waldo@example.com",
"password": "PleaseChangeMeImmediately",
"roles": [
"Admin"
],
"tenantUrn": "urn:tenant:uuid:346e742e-2f1e-4d91-9ffe-7b38eec6219c"
}
}Example 2
{
"name": "Example Company",
"username": "waldo@example.com"
}201 CREATED
{
"urn": "urn:tenant:uuid:346e742e-2f1e-4d91-9ffe-7b38eec6219c",
"admin": {
"urn": "urn:user:uuid:34068f4d-12a5-4546-80f8-9f84b762db20",
"username": "waldo@example.com",
"password": "PleaseChangeMeImmediately",
"roles": [
"Admin"
],
"tenantUrn": "urn:tenant:uuid:346e742e-2f1e-4d91-9ffe-7b38eec6219c"
}
}Update - PUT /tenants/{urn}
Update an existing Tenant.
PUT /tenants/urn:tenant:uuid:346e742e-2f1e-4d91-9ffe-7b38eec6219c
{
"active": false,
"name": "My Example Company"
}204 NO CONTENT
Find by URN - GET /tenants/{urn}
Get a Tenant by its URN.
GET /tenants/urn:tenant:uuid:346e742e-2f1e-4d91-9ffe-7b38eec6219c
200 OK
{
"urn": "urn:tenant:uuid:346e742e-2f1e-4d91-9ffe-7b38eec6219c",
"active": true,
"name": "My Example Company"
}Find by Name - GET /tenants/?name={name}
Get a Tenant by its name.
GET /tenants?name=My%20Example%20Company
200 OK
{
"urn": "urn:tenant:uuid:346e742e-2f1e-4d91-9ffe-7b38eec6219c",
"active": true,
"name": "My Example Company"
}GET /tenants
200 OK
[
{
"urn": "urn:tenant:uuid:346e742e-2f1e-4d91-9ffe-7b38eec6219c",
"active": true,
"name": "My Example Company"
},
{
"urn": "urn:tenant:uuid:f1e4ff26-2a5f-41c6-8533-4994cb2cceec",
"active": true,
"name": "Another Example Company"
}
]User Endpoints
Create - POST /users
Create a new User belonging to the Tenant of the authenticated User.
POST /users
Example 1
{
"active": true,
"roles": [
"User"
],
"username": "bob@example.com",
"emailAddress": "bob@example.com",
"givenName": "Bob",
"surname": "Smith"
}201 CREATED
{
"urn": "urn:user:uuid:68a76616-3748-4bc2-93c1-3940b47abb7f",
"username": "bob@example.com",
"password": "PleaseChangeMeImmediately",
"roles": [
"User"
],
"tenantUrn": "urn:tenant:uuid:69bb7c6a-a43b-493d-8e9d-e5a3ed65728a"
}Example 2
{
"roles": [
"User"
],
"username": "bob@example.com"
}201 CREATED
{
"urn": "urn:user:uuid:68a76616-3748-4bc2-93c1-3940b47abb7f",
"username": "bob@example.com",
"password": "PleaseChangeMeImmediately",
"roles": [
"User"
],
"tenantUrn": "urn:tenant:uuid:69bb7c6a-a43b-493d-8e9d-e5a3ed65728a"
}Update - PUT /users/{urn}
Update the existing User with the specified URN.
PUT /users/urn:user:uuid:68a76616-3748-4bc2-93c1-3940b47abb7f
{
"active": false,
"password": "xyz1234567"
}204 NO CONTENT
Find by URN - GET /users/{urn}
Get the User with the specified URN.
GET /users/urn:user:uuid:68a76616-3748-4bc2-93c1-3940b47abb7f
200 OK
{
"urn": "urn:user:uuid:68a76616-3748-4bc2-93c1-3940b47abb7f",
"active": true,
"roles": [
"User"
],
"username": "bob@example.com",
"emailAddress": "bob@example.com",
"givenName": "Bob",
"surname": "Smith",
"tenantUrn": "urn:tenant:uuid:69bb7c6a-a43b-493d-8e9d-e5a3ed65728a"
}Find by Name - GET /users?name={name}
Get the User with the specified name.
GET /users
200 OK
[
{
"urn": "urn:user:uuid:68a76616-3748-4bc2-93c1-3940b47abb7f",
"active": true,
"roles": [
"User"
],
"username": "bob@example.com",
"emailAddress": "bob@example.com",
"givenName": "Bob",
"surname": "Smith",
"tenantUrn": "urn:tenant:uuid:69bb7c6a-a43b-493d-8e9d-e5a3ed65728a"
},
{
"urn": "urn:user:uuid:af37520d-86ad-49fe-be25-92ce269fbda4",
"active": true,
"roles": [
"Admin"
],
"username": "jane@example.com",
"emailAddress": "jane@example.com",
"givenName": "Jane",
"surname": "Smith",
"tenantUrn": "urn:tenant:uuid:69bb7c6a-a43b-493d-8e9d-e5a3ed65728a"
}
]Delete - DELETE /users/{urn}
Delete the User with the specified URN.
DELETE /users/urn:role:uuid:fcdf5432-49a8-45ef-96a2-94a022022860
204 NO CONTENT
Roles Endpoints
Create - POST /roles/
Create a Role.
POST /roles/
{
"name": "User",
"authorities": [
"https://authorities.smartcosmos.net/things/read"
]
}201 CREATED
{
"urn": "urn:role:uuid:fcdf5432-49a8-45ef-96a2-94a022022860",
"name": "User",
"active": true,
"authorities": [
"https://authorities.smartcosmos.net/things/read"
],
"tenantUrn": "urn:tenant:uuid:69bb7c6a-a43b-493d-8e9d-e5a3ed65728a"
}Update - PUT /roles/{urn}
Update an existing Role.
PUT /roles/urn:role:uuid:fcdf5432-49a8-45ef-96a2-94a022022860
{
"name": "User",
"authorities": [
"https://authorities.smartcosmos.net/things/read"
]
}204 NO CONTENT
Find by URN - GET /roles/{urn}
Get the Role with the specified URN.
GET /roles/urn:role:uuid:318a9fae-0218-486c-b9f6-86f76b2ff6af
200 OK
{
"urn": "urn:role:uuid:318a9fae-0218-486c-b9f6-86f76b2ff6af",
"name": "Admin",
"active": true,
"authorities": [
"https://authorities.smartcosmos.net/things/read",
"https://authorities.smartcosmos.net/things/create"
],
"tenantUrn": "urn:tenant:uuid:69bb7c6a-a43b-493d-8e9d-e5a3ed65728a"
}Find by Name - GET /roles?name={name}
Get the Role with the specified name.
GET /roles
200 OK
[
{
"urn": "urn:role:uuid:318a9fae-0218-486c-b9f6-86f76b2ff6af",
"name": "Admin",
"active": true,
"authorities": [
"https://authorities.smartcosmos.net/things/read",
"https://authorities.smartcosmos.net/things/create"
],
"tenantUrn": "urn:tenant:uuid:69bb7c6a-a43b-493d-8e9d-e5a3ed65728a"
},
{
"urn": "urn:role:uuid:fcdf5432-49a8-45ef-96a2-94a022022860",
"name": "User",
"active": true,
"authorities": [
"https://authorities.smartcosmos.net/things/read"
],
"tenantUrn": "urn:tenant:uuid:69bb7c6a-a43b-493d-8e9d-e5a3ed65728a"
}
]Delete - DELETE /roles/{urn}
Delete the Role with the specified URN.
DELETE /roles/urn:role:uuid:fcdf5432-49a8-45ef-96a2-94a022022860
204 NO CONTENT
Configuration
Below is a typical smartcosmos-edge-user-devkit.yml file, which provides configuration
for the service. Individual endpoints can be turned off by setting their respective
enabled flags to false. The default behavior (i.e., in the absence of an enabled
flag for the endpoint) is enabled.
For a docker-compose deployment of
SMART COSMOS DevKit,
the file is located in
the config directory. For a deployment in which the developer
is running her own
SMART COSMOS config-server
service, the file is located in the top directory of
smartcosmos-cluster-config.
server:
port: 45371
spring:
datasource:
url: jdbc:mysql://{dbServer}/{dbName}
username: {dbUser}
password: {dbPassword}
driver-class-name: org.mariadb.jdbc.Driver
test-on-borrow: true
validation-query: SELECT 1
jpa:
hibernate:
# Edge User DevKit and User Details DevKit share the database scheme
ddl-auto: update
naming_strategy: org.hibernate.cfg.EJB3NamingStrategy
smartcosmos:
security:
enabled: true
endpoints:
tenants:
enabled: true
create.enabled: true
read:
urn.enabled: true
all.enabled: true
update.enabled: true
users:
enabled: true
create.enabled: true
read:
urn.enabled: true
all.enabled: true
update.enabled: true
delete.enabled: true
roles:
enabled: true
create.enabled: true
read:
urn.enabled: true
all.enabled: true
update.enabled: true
delete.enabled: true