Update project documentation with example requests and responses (#220)
Update documentation with example requests and responses in accordance with new API changes. Add detailed flow explanation. Update readme with valid snippet. Signed-off-by: Aleksandar Novakovic <anovakovic01@gmail.com>
This commit is contained in:
Aleksandar Novaković
Dejan Mijić
parent
703d0543af
commit
36a00f3464
|
|
@ -34,7 +34,6 @@ Before proceeding, install the following prerequisites:
|
|||
Once everything is installed, execute the following commands from project root:
|
||||
|
||||
```bash
|
||||
cd docker/
|
||||
docker-compose up -f docker/docker-compose.yml -d
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -9,7 +9,6 @@ Before proceeding, install the following prerequisites:
|
|||
Once everything is installed, execute the following commands from project root:
|
||||
|
||||
```bash
|
||||
cd docker/
|
||||
docker-compose up -f docker/docker-compose.yml -d
|
||||
```
|
||||
|
||||
|
|
@ -17,11 +16,30 @@ docker-compose up -f docker/docker-compose.yml -d
|
|||
|
||||
### Account creation
|
||||
|
||||
TBD
|
||||
Use the Mainflux API to create user account:
|
||||
|
||||
```
|
||||
curl -s -S -i --cacert docker/ssl/certs/mainflux-server.crt --insecure -X POST -H "Content-Type: application/json; charset=utf-8" https://localhost/users -d '{"email":"john.doe@email.com", "password":"123"}'
|
||||
```
|
||||
|
||||
Note that when using official `docker-compose`, all services are behind `nginx`
|
||||
proxy and all traffic is `TLS` encrypted.
|
||||
|
||||
### Obtaining an authorization key
|
||||
|
||||
TBD
|
||||
In order for this user to be able to authenticate to the system, you will have
|
||||
to create an authorization token for him:
|
||||
|
||||
```
|
||||
curl -s -S -i --cacert docker/ssl/certs/mainflux-server.crt --insecure -X POST -H "Content-Type: application/json; charset=utf-8" https://localhost/tokens -d '{"email":"john.doe@email.com", "password":"123"}'
|
||||
```
|
||||
|
||||
Response should look like this:
|
||||
```
|
||||
{
|
||||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MjMzODg0NzcsImlhdCI6MTUyMzM1MjQ3NywiaXNzIjoibWFpbmZsdXgiLCJzdWIiOiJqb2huLmRvZUBlbWFpbC5jb20ifQ.cygz9zoqD7Rd8f88hpQNilTCAS1DrLLgLg4PRcH-iAI"
|
||||
}
|
||||
```
|
||||
|
||||
## System provisioning
|
||||
|
||||
|
|
@ -30,35 +48,195 @@ an authorization key.
|
|||
|
||||
### Provisioning devices
|
||||
|
||||
TBD
|
||||
Devices are provisioned by executing request `POST /clients`, with a
|
||||
`"type":"device"` specified in JSON payload. Note that you will also need
|
||||
`user_auth_token` in order to provision clients (both devices and application)
|
||||
that belong to this particular user.
|
||||
|
||||
```
|
||||
curl -s -S -i --cacert docker/ssl/certs/mainflux-server.crt --insecure -X POST -H "Content-Type: application/json; charset=utf-8" -H "Authorization: <user_auth_token>" https://localhost/clients -d '{"type":"device", "name":"weio"}'
|
||||
```
|
||||
|
||||
Response will contain `Location` header whose value represents path to newly
|
||||
created client:
|
||||
|
||||
```
|
||||
HTTP/1.1 201 Created
|
||||
Content-Type: application/json; charset=utf-8
|
||||
Location: /clients/81380742-7116-4f6f-9800-14fe464f6773
|
||||
Date: Tue, 10 Apr 2018 10:02:59 GMT
|
||||
Content-Length: 0
|
||||
```
|
||||
|
||||
### Provisioning applications
|
||||
|
||||
TBD
|
||||
Applications are provisioned by executing HTTP request `POST /clients`, with
|
||||
`"type":"app"` specified in JSON payload.
|
||||
|
||||
```
|
||||
curl -s -S -i --cacert docker/ssl/certs/mainflux-server.crt --insecure -X POST -H "Content-Type: application/json; charset=utf-8" -H "Authorization: <user_auth_token>" https://localhost/clients -d '{"type":"app", "name":"myapp"}'
|
||||
```
|
||||
|
||||
Response will contain `Location` header whose value represents path to newly
|
||||
created client (same as for devices):
|
||||
|
||||
```
|
||||
HTTP/1.1 201 Created
|
||||
Content-Type: application/json; charset=utf-8
|
||||
Location: /clients/cb63f852-2d48-44f0-a0cf-e450496c6c92
|
||||
Date: Tue, 10 Apr 2018 10:33:17 GMT
|
||||
Content-Length: 0
|
||||
```
|
||||
|
||||
### Retrieving provisioned clients
|
||||
|
||||
TBD
|
||||
In order to retrieve data of provisioned clients that is written in database, you
|
||||
can send following request:
|
||||
|
||||
```
|
||||
curl -s -S -i --cacert docker/ssl/certs/mainflux-server.crt --insecure -H "Authorization: <user_auth_token>" https://localhost/clients
|
||||
```
|
||||
|
||||
Notice that you will receive only those clients that were provisioned by
|
||||
`user_auth_token` owner.
|
||||
|
||||
```
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=utf-8
|
||||
X-Count: 4
|
||||
Date: Tue, 10 Apr 2018 10:50:12 GMT
|
||||
Content-Length: 1105
|
||||
|
||||
{
|
||||
"clients": [
|
||||
{
|
||||
"id": "81380742-7116-4f6f-9800-14fe464f6773",
|
||||
"type": "device",
|
||||
"name": "weio",
|
||||
"key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE1MjMzNTQ1NzksImlzcyI6Im1haW5mbHV4Iiwic3ViIjoiODEzODA3NDItNzExNi00ZjZmLTk4MDAtMTRmZTQ2NGY2NzczIn0.5s8s1hlK-l30kQAyHxEZO_M2NIQw53MQuy7b3Wf3OOE"
|
||||
},
|
||||
{
|
||||
"id": "cb63f852-2d48-44f0-a0cf-e450496c6c92",
|
||||
"type": "app",
|
||||
"name": "myapp",
|
||||
"key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE1MjMzNTYzOTcsImlzcyI6Im1haW5mbHV4Iiwic3ViIjoiY2I2M2Y4NTItMmQ0OC00NGYwLWEwY2YtZTQ1MDQ5NmM2YzkyIn0.FE6DWB3yJmBb8uojpQJaKUEbD0Elrjx0HhJA28bVzkU"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Removing clients
|
||||
|
||||
TBD
|
||||
In order to remove you own client you can send following request:
|
||||
|
||||
```
|
||||
curl -s -S -i --cacert docker/ssl/certs/mainflux-server.crt --insecure -X DELETE -H "Authorization: <user_auth_token>" https://localhost/clients/<client_id>
|
||||
```
|
||||
|
||||
### Provisioning channels
|
||||
|
||||
TBD
|
||||
Channels are provisioned by executing request `POST /channels`:
|
||||
|
||||
```
|
||||
curl -s -S -i --cacert docker/ssl/certs/mainflux-server.crt --insecure -X POST -H "Content-Type: application/json; charset=utf-8" -H "Authorization: <user_auth_token>" https://localhost/channels -d '{"name":"mychan"}'
|
||||
```
|
||||
|
||||
After sending request you should receive response with `Location` header that
|
||||
contains path to newly created channel:
|
||||
|
||||
```
|
||||
HTTP/1.1 201 Created
|
||||
Content-Type: application/json; charset=utf-8
|
||||
Location: /channels/19daa7a8-a489-4571-8714-ef1a214ed914
|
||||
Date: Tue, 10 Apr 2018 11:30:07 GMT
|
||||
Content-Length: 0
|
||||
```
|
||||
|
||||
### Retrieving provisioned channels
|
||||
|
||||
TBD
|
||||
To retreve provisioned channels you should send request to `/channels` with
|
||||
authorization token in `Authorization` header:
|
||||
|
||||
```
|
||||
curl -s -S -i --cacert docker/ssl/certs/mainflux-server.crt --insecure -H "Authorization: <user_auth_token>" https://localhost/channels
|
||||
```
|
||||
|
||||
You should receive response similar to this:
|
||||
|
||||
```
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=utf-8
|
||||
X-Count: 2
|
||||
Date: Tue, 10 Apr 2018 11:38:06 GMT
|
||||
Content-Length: 139
|
||||
|
||||
{
|
||||
"channels": [
|
||||
{
|
||||
"id": "19daa7a8-a489-4571-8714-ef1a214ed914",
|
||||
"name": "mychan"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Note that you will receive only those channels that were created by authorization
|
||||
token's owner.
|
||||
|
||||
### Removing channels
|
||||
|
||||
TBD
|
||||
In order to remove specific channel you should send following request:
|
||||
|
||||
```
|
||||
curl -s -S -i --cacert docker/ssl/certs/mainflux-server.crt --insecure -X DELETE -H "Authorization: <user_auth_token>" https://localhost/channels/<channel_id>
|
||||
```
|
||||
|
||||
## Access control
|
||||
|
||||
TODO: describe how to connect & disconnect clients to/from channels
|
||||
Channel can be observed as a communication group of clients. Only clients that
|
||||
are connected to the channel can send and receive messages from other clients
|
||||
in this channel. Clients that are not connected to this channel are not allowed
|
||||
to communicate over it.
|
||||
|
||||
Only user, who is the owner of a channel and of the clients, can connect the
|
||||
clients to the channel (which is equivalent of giving permissions to these clients
|
||||
to communicate over given communication group).
|
||||
|
||||
To connect client to the channel you should send following request:
|
||||
|
||||
```
|
||||
curl -s -S -i --cacert docker/ssl/certs/mainflux-server.crt --insecure -X PUT -H "Authorization: <user_auth_token>" https://localhost/channels/<channel_id>/clients/<client_id>
|
||||
```
|
||||
|
||||
You can observe which clients are connected to specific channel:
|
||||
|
||||
```
|
||||
curl -s -S -i --cacert docker/ssl/certs/mainflux-server.crt --insecure -H "Authorization: <user_auth_token>" https://localhost/channels/<channel_id>
|
||||
```
|
||||
|
||||
You should receive response with the lists of connected clients in `connected` field
|
||||
similar to this one:
|
||||
|
||||
```
|
||||
{
|
||||
"id": "19daa7a8-a489-4571-8714-ef1a214ed914",
|
||||
"name": "mychan",
|
||||
"connected": [
|
||||
{
|
||||
"id": "81380742-7116-4f6f-9800-14fe464f6773",
|
||||
"type": "device",
|
||||
"name": "weio",
|
||||
"key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE1MjMzNTQ1NzksImlzcyI6Im1haW5mbHV4Iiwic3ViIjoiODEzODA3NDItNzExNi00ZjZmLTk4MDAtMTRmZTQ2NGY2NzczIn0.5s8s1hlK-l30kQAyHxEZO_M2NIQw53MQuy7b3Wf3OOE"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
If you want to disconnect your device from the channel, send following request:
|
||||
|
||||
```
|
||||
curl -s -S -i --cacert docker/ssl/certs/mainflux-server.crt --insecure -X DELETE -H "Authorization: <user_auth_token>" https://localhost/channels/<channel_id>/clients/<client_id>
|
||||
```
|
||||
|
||||
## Sending messages
|
||||
|
||||
|
|
@ -68,4 +246,10 @@ of message publishing for each of the supported protocols.
|
|||
|
||||
### HTTP
|
||||
|
||||
TBD
|
||||
To publish message over channel, client should send following request:
|
||||
|
||||
```
|
||||
curl -s -S -i --cacert docker/ssl/certs/mainflux-server.crt --insecure -X POST -H "Content-Type: application/senml+json" -H "Authorization: <client_token>" https://localhost/channels/<channel_id>/messages -d -d '[{"bn":"some-base-name:","bt":1.276020076001e+09, "bu":"A","bver":5, "n":"voltage","u":"V","v":120.1}, {"n":"current","t":-5,"v":1.2}, {"n":"current","t":-4,"v":1.3}]'
|
||||
```
|
||||
|
||||
Note that you should always send array of messages in senML format.
|
||||
Loading…
Reference in New Issue