Some response objects can be huge, you can reduce the object be telling the server which fields (JSON attributes) you want to include within the object. When fields parameter is omitted from the request, the server will always return all attributes of the return object.
It's strongly recommend you using fields parameter. It will make the server response faster with smaller memory footprint.
Let's get the demo IoT device:
$ curl https://cloud.vicotee.com/api/demo/device
> HTTP/1.1 200 OK
> Connection: keep-alive
> Vary: Accept-Encoding
> Transfer-Encoding: chunked
> Content-Type: application/json
> X-Application-Context: gateway-zuul:dev:8000
> Date: Wed, 25 May 2022 06:28:06 GMT
> {
> "id": "1234567890",
> "uuid": "1234560000000001",
> "name": "Meeting room 'orange'",
> "description": "This is a demo",
> "sn": "220190364",
> "pn": "1101144"
> }The JSON object in response contains following fields (attributes): id, uuid, name, description, sn and pn.
Let say if you are only interested in the name and serial number, then you send the request like this:
$ curl https://cloud.vicotee.com/api/demo/device?fields=name,sn
> HTTP/1.1 200 OK
> Connection: keep-alive
> Vary: Accept-Encoding
> Transfer-Encoding: chunked
> Content-Type: application/json
> X-Application-Context: gateway-zuul:dev:8000
> Date: Wed, 25 May 2022 06:28:06 GMT
> {
> "id": "1234567890",
> "name": "Meeting room 'orange'",
> "sn": "220190364"
> }The field id is mandatory, and most JSON objects contain an ID, so you can not omit the id.
Most IDs returned from Vicotee's server are string data types, even they are a number. If you use a strong type language, you may want to convert them to a long data type.
Fields can also be used when you request the server to update certain fields for an object.
Let's update the name of our demo device.
curl -i -H "Content-Type: application/json" \
-d '{"id": "1234567890", "name" : "new name", "sn" : "220190364"}' \
https://cloud.vicotee.com/api/demo/device?fields=nameBy telling the server just to update the name, we guarantee all other fields will be intact as they are.
It is important to know that if you request an object with certain fields and then update the same object, it is very important to include fields in the update request parameter. If you forget to do so, the server will update the fields you have changed and set all other fields to null (or empty).
Retrieving the device with name field only:
$ curl https://cloud.vicotee.com/api/demo/device?fields=name
> HTTP/1.1 200 OK
> Connection: keep-alive
> Vary: Accept-Encoding
> Transfer-Encoding: chunked
> Content-Type: application/json
> X-Application-Context: gateway-zuul:dev:8000
> Date: Wed, 25 May 2022 06:28:06 GMT
> {
> "id": "1234567890",
> "name": "Meeting room 'orange'"
> }
Next, you request the server to update the name to "Meeting room ’blue'", and you therefor passing on the request object you retrieved above, this time your request is without fields=name. The server will automatically erase other fields because they are not presented in the request JSON object.
curl -i -H "Content-Type: application/json" \
-d '{"id": "1234567890", "name" : "Meeting room ’blue'"}' \
https://cloud.vicotee.com/api/demo/device
Let retrieve the whole device again and see how it look like. This time we retrieve all fields, by omit the fields from the request parameter:
$ curl https://cloud.vicotee.com/api/demo/device
> HTTP/1.1 200 OK
> Connection: keep-alive
> Vary: Accept-Encoding
> Transfer-Encoding: chunked
> Content-Type: application/json
> X-Application-Context: gateway-zuul:dev:8000
> Date: Wed, 25 May 2022 06:28:06 GMT
> {
> "id": "1234567890",
> "name": "Meeting room 'orange'"
> }As you can see, the demo device only contain id and name. All other fields are missing. fields parameter is a useful feature, but incorrect use of it can cause permanent damage on your data.
It's important to use the same fields for GET and POST request.