Accessing RESTful API’s

HTTP has been around for a long time and is universally used in many languages. This article will help you understand what a RESTful Web service is and how to leverage one from nearly any platform.

What is a RESTful Web service?

A RESTful service exposes a set of resources that identify the targets of interaction with its clients. Resources are identified by URI’s which provide an easy way to access it globally.

Resources are manipulated using the same methods that HTTP uses - PUT, GET, POST and DELETE. PUT creates a new resource, GET retrieves the current state of the resource, POST transfers a new state to the resource, and DELETE can remove that same resource. Note: Post can also be used in the same way as GET depending on the service.

RESTful services are often very descriptive about what they offer and can do. More often than not while working with a RESTful service, they will decouple the resources they offer from the format they offer them in. This allows for many different types of services. The most common occurring formats are HTML, XML, plain text and JSON.

Pros

• Easy to interpret calls.
• Accessible from any platform that supports HTTP calls.
• Many different formats available to display resources with.
• No need for heavy code changes to code wrappers (SOAP RPC wrappers would require a full update, whereas there are a few small changes when the REST API changes).

Cons

• RESTful APIs are not a good fit for resources that are not organized. This can however be minimized by allowing parameters to comb down the results. Be warned though that this can impact performance.
• Often times you have to be careful of how the service is being used (Limiting request amounts etc.). Usually this requires cumbersome tokens or types of authentication which can increase latency in the requests.
• Depending on the resource returned and limiting on requests, bandwidth can be a concern with RESTful APIs.

Example

Today my code of choice will be one we often use in our web projects and is often used around the world: PHP. The code I show will be pseudo for the most part and the key concepts can be copied over to almost any other language that can do the HTTP calls required. Along with PHP I will be using cURL to make my requests and return the data.
First off we need a service to test. I have chosen to use jsonplaceholder.typicode.com as ours. This service is a free that is often used for tutorials like this one.
So let’s set up an easy little wrapper for the API calls.

Let’s start with line 10. This line simply initializes curl so we can make our calls, nothing fancy.
Next we wrap everything we do in a try/catch/finally this will allow us to catch any curl errors which we throw if the result comes back false and allows us to close off curl.
There is no line to show this but by default the request will be a GET request. If you wanted to use post you could optionally use the following:

Line 12 forces the return to go to our object rather than attempt to put it in a browser.
Line 14 is the ‘magic’ we just execute our curl request and the API will return a result. This can either be false if an error or it can be the data we want.
Line 19 I end up using json_decode to return the results, for this example I will be getting my data back as a JSON object however this can be tweaked for pretty much any data format.

Ok so now that we have our wrapper let’s use it.

Really simple here - we pass in the URL on line 28 and get our data back on line 30. Here is a print of what we get from $info.

{ "userId": 1, "id": 1, "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit", "body": "quia et suscipit suscipit recusandae consequuntur expedita et cum reprehenderit molestiae ut ut quas totam nostrum rerum est autem sunt rem eveniet architecto" }

This is a nice easy JSON array of data we could use.

In Conclusion

RESTful APIs are great lightweight and flexible tools that can be leveraged from almost any platform. They are great for scalability and ease of use however they can have issue with bandwidth and performance depending on usage. If you are trying to leverage a service on multiple platforms in a variety of forms REST is the way to go.

Thanks for reading and if you have any questions, please leave a comment below.