RESTful APIs Part 5 - Using REST

By now you might be thinking,

"Enough already, I am tired of the theory, how long until we can actually talk about how to use a RESTful API?"

Well that is what I will be covering today.

To start us off we have to pick a RESTful API to interact with. While RESTful APIs are easier to understand then all the non-RESTful APIs I have seen it is still essential that we have some documentation. So to start out we will use the Swagger's Pet Store Demo.

If you are creating a new API you should check Swagger out. Swagger is a specification for writing RESTful API documentation with a large community of tooling written, which makes it easier to get started on documentation and implementation.

Getting started

We picked Swagger's Pet Store Demo because it is a simple API with some documentation. Additionally the documentation allows you to interact with the API directly, which can get you started in remarkable short order since you can make your requests right from the documentation without having to write any code. This makes it so you can quickly test the API and see how you can get the information you need.

The first thing you should notice is that there are three different resources: pet, store, and user. If you click on any of those resources it shows the operations you can perform on each resource.

Click on "pet"

If you click on pet you will notice there is a list of operations you can perform for the pet resource. For each operation there is a description on the right. As you look through the list you will see most of the operations you would expect on a RESTful resource.

  • POST to create a pet
  • GET to read a specific pet
  • PUT to update a pet
  • DELETE to delete a pet

There are also a few other operations which are different. These are not necessarily perfectly RESTful since they are either changing the use of the method, or adding something extra to the URL.

For example, there is a POST with the {petId} and then uploadImage. This is an action that is being performed on the put, uploading an image. This may not be exactly RESTful but you will find that you often have to do something outside of CRUD (Create, Read, Update, Delete) or something is simpler if you do not have to create a new resource, in this case just for the image. In these cases adding an action is often the easiest way to move forward. Developers spend countless hours debating the best way to do "actions" and there are lots of different approaches which are taken so if you are connecting to an API you have to be flexible, as there may be some exceptions.

Click on "GET /pet/findByStatus"

As you expand this operation you will see that there is some information on the implementation as well as a way to look at the Model (how it is stored in the database), or an Example Value. The example value can be viewed in XML or JSON, this can be changed in the dropdown below the example value, and is representative of a response from that operation.

There is also an area describing each of the parameters you can send. In this case there is a status for the pet you can send. So if you want to see all the sold pets you send a status of sold.

Go ahead and select the sold status and click the Try it out! button.

Congratulations! You have made a RESTful API call. That shouldn't be too amazing since your browser is constantly making API calls to RESTful web services as you navigate through the web.

Below the button it shows the curl command which will get the same response. For me it looks like this:

curl -X GET --header 'Accept: application/json' 'http://petstore.swagger.io/v2/pet/findByStatus?status=sold'

You can take this command and if you are on an OS with the curl tool installed (Linux, Mac) you can copy and paste the code into the command line and run it to get the same results. Curl is a nice tool to make simple one off calls to see how an API works. One of the reasons you will often see examples where they provide the curl command as they did here is that looking at the curl command you can quickly see the important details of the request such as the method, any headers, and the URL.

Below that you get the URL, the body of the response, and the response code. I got 200 meaning it was successful and the headers for the response, which often are not particularly important.

Continuing on

We took a look at a single operation for a single resource which may not seem like much but in reality that is basically all there is to it. In some ways it seems like a let down but the simplicity is why REST is so amazing.

There will always be more details you have to figure out, such as how do I use my tool to connect to the API instead of with Swagger's built in tool. However, those will depend on what you are using, is it AngularJS, Angular2, jQuery, BackboneJS, Django, Ruby on Rails, C++, Java, etc...

So I while I can't explain every use case feel free to ask any questions you might have. I am considering showing an example using a specific tool so if you have a suggestion let me know.

comments powered by Disqus