Making REST work for you is a cornerstone of modern web application development. In this article I take a look at a case study in creating and utilising a REST API.

The Specification

The requirement came from a small organisation that manages a number of assets and assigns them to clients. The organisation had several needs:

• Track which clients had which assets.
• Track payments received and outstanding bills.
• Create and send documents to their clients, including bills and notifications.
• The ability to access the system anywhere, on desktop or mobile.

The Design

To fulfil the access anywhere requirement, the best solution was a web application. It became clear to me early in the design phase that sending a pre-populated page to the web client would create a bad user experience. Instead the user would be best served by receiving an unpopulated page and then receiving the data to populate the section of the page they were working in. The following process flow for accessing an asset came to mind:

1. User requests the page for an asset.
2. The server returns an unpopulated asset page. The page is divided into tabs of contextually related data.
3. The asset page requests the data needed to populate the currently displayed tab.
4. The server returns the requested data.
5. The asset page populates the displayed fields with the returned data.

If the user changes tabs, only steps 3 onward needs to be repeated.

This whole process cuts down on overhead, allowing the user to get to the data they wish to see faster.

Implementing and Making a REST API

From the client-side perspective, the obvious choice for sending and receiving requests was AJAX. From there it was a clear step to use a REST API to handle the requests on the server. I needed to start making REST work for me.

At first I was coding the responses for each request handler individually. However I quickly realised that I had naturally standardised the format of the returned data for lists and single records. If each request resulted in a response in a standard format, I should have a standard response class! Which is what I made next. My responses could return any or all of the following:

• A “data” block: either a single object for a single record or an array of objects for a list of records.
• A “sort” block: an array of sort order definitions. Included only if the “data” block was an array.
• A “message” block: a simple text message containing status information.

My response class started with each of these set to empty and a creation state set to false. If the request was a POST, then creation state would be set to true. If none of the “blocks” were populated, then the HTTP status would return “No Content”. Otherwise the HTTP status would either return “Created” or “OK”, depending on the creation state. To round things off, I added a function that would override anything that had previously been set and return an “error description” block along with a HTTP status error code – both defined on the function’s call.

Once my class was ready I was able to making REST API calls in my web pages, knowing I would always get a standardised response from the backend. Meanwhile, I was also saved from hours of typing functionally similar responses.

Working With the REST API

With my REST API in place I was ready to start making REST work for me. When building a list page, I would start with an empty table and fire off a GET request for the list. The returned data would then populate the table. When building a record page, I would start with empty fields and fire off a GET request for the record. The returned data would then populate the fields. Editing a field would use a PATCH request to update the database automatically. Creating a record would make a POST request. Finally, to remove a record I would use a DELETE request.

All REST requests received by the server would be checked for user access permissions before returning a response. REST really was working for me now.

SAMWare UK creates bespoke solutions and websites. Contact us to arrange a chat to discuss your needs and for a free no obligation quote.