Close

REST v4

A project log for Internet of Plants (IoP)

Internet of Plants is essentially a mesh-network of plant master and slave controllers for better & less plant care with affordable pricing

Bilal MahmoudBilal Mahmoud 04/02/2017 at 13:210 Comments

For the fourth time completely rebuilt how the REST-API works. I did this because hit a wall concerning reusability, simplicity, and expandability.

Instead of having one path for one interaction, I regrouped them for a better RESTful representation and a less hacky approach.

To show the changes I made, these are the old URLs in REST v3:

/create/message
/create/plant
/create/plant/register
/create/responsible
/delete/responsible/<r_uuid>
/execute/discover
/get/day/night/time
/get/discovered/<int:registered>/names
/get/discovered/<int:registered>/names/extended
/get/message/<m_uuid>
/get/message/<m_uuid>/content
/get/messages/names
/get/plant/<p_uuid>
/get/plant/<p_uuid>/created_at
/get/plant/<p_uuid>/intervals
/get/plant/<p_uuid>/location
/get/plant/<p_uuid>/message
/get/plant/<p_uuid>/responsible
/get/plant/<p_uuid>/responsible/email
/get/plant/<p_uuid>/responsible/username
/get/plant/<p_uuid>/responsible/wizard
/get/plant/<p_uuid>/sensor/<s_uuid>/latest
/get/plant/<p_uuid>/sensor/<sensor>/<any(high, low):mode>/today/<any(yes,no):if_no_data_days_before>
/get/plant/<p_uuid>/sensor/<sensor>/<any(high,low):mode>/ever
/get/plant/<p_uuid>/sensor/<sensor>/data
/get/plant/<p_uuid>/sensor/<sensor>/data/<float:until>
/get/plant/<p_uuid>/sensor/<sensor>/data/count
/get/plant/<p_uuid>/sensor/<sensor>/data/current
/get/plant/<p_uuid>/sensor/<sensor>/data/start/<int:start>/stop/<int:stop>
/get/plant/<p_uuid>/sensor/<sensor>/prediction
/get/plant/<p_uuid>/sensor/<sensor>/range
/get/plant/<p_uuid>/sensors/range
/get/plant/<p_uuid>/status/average
/get/plant/<p_uuid>/status/online/
/get/plant/<p_uuid>/survived
/get/plant/<p_uuid>/type
/get/plant/<plant>/average_status/percent
/get/plant/<plant>/current_status
/get/plant/current/host
/get/plants/master
/get/plants/name
/get/plants/name/extended
/get/plants/satisfaction
/get/plants/sensors/satisfaction
/get/responsible/<r_uuid>
/get/responsible/persons
/get/sensor/<s_uuid>
/get/sensor/<sensor>/range
/get/sensor/<sensor>/unit
/update/current/host/to/localhost
/update/day/night/time
/update/notification/message
/update/plant/<p_uuid>/alive/<any(online,offline):mode>/add
/update/plant/<p_uuid>/connection-lost/duration
/update/plant/<p_uuid>/location
/update/plant/<p_uuid>/name
/update/plant/<p_uuid>/non-persistant/duration
/update/plant/<p_uuid>/notification/duration
/update/plant/<p_uuid>/ranges
/update/plant/<p_uuid>/responsible
/update/plant/<p_uuid>/satisfaction/level/add
/update/plant/<p_uuid>/satisfaction/level/reset
/update/plant/<p_uuid>/type
/update/responsible
/update/responsible/wizard

Those are many paths to remember and to use, huh?

In REST v3 only /get/ essentially used the GET method. Everything else, more or less consistent, used the POST method.

What exactly changed? Instead of having 65 endpoints, which aren't particularly well ordered or have any structure what so ever, the new API now has 18 endpoints and is a bit faster. The new endpoints are using, instead of only one, multiple HTTP request method. Just for comparison, here's a small list of the new paths and the supported methods:

/day/night                         (GET, POST)
/discover                          (GET, PUT - substitute for execute)
/host                              (GET, POST)
/messages                          (GET, PUT)             
/messages/<m_uuid>                 (GET, POST)
/persons                           (GET, PUT)
/persons/<r_uuid>                  (GET, POST)
/plants                            (GET, PUT)
/plants/<p_uuid>                   (GET, POST)
/plants/<p_uuid>/message           (GET)
/plants/<p_uuid>/responsible       (GET) 
/plants/<p_uuid>/sensor            (GET)
/plants/<p_uuid>/sensor/<s_uuid>   (GET)
/plants/<p_uuid>/status            (GET)
/responsibles                      (redirect to /persons - REST v3 artifact)
/responsibles/<r_uuid>             (redirect to /persons/<r_uuid> - REST v3 artifact)
/sensors                           (GET)
/sensors/<s_uuid>                  (GET)

As you can see from the now available endpoints, every object has only a fraction of the paths used before. Essentially every object now has two endpoints except one. The object that is the exception is the plant. This something is one of the more important objects used for saving a variety of different data.

Another new feature is the uniform structure of the data returned in JSON:

{"code": 200, "content": []}
A little explanation: content is guaranteed to be either an object or array. If no data is present, an empty array is going to get returned. The code is a typical HTTP code, saying if something possibly went very wrong.

Also: REST v4 is currently not tested and REST v3 is still included in this build, because of moving purposes and testing, but is going to get removed in REST v4.1

Discussions