in Tutorials

Web services by example 3 of 3

I have built many WebServices APIs over the years. I dealt with multiple server CMS platforms (WordPress, Joomla), in-house servers, PHP, ASP many of which needed some form of RESTful api to communicate with mobile applications.

Here’s the final of my three part tutorial that develops a RESTful web service by example.

HTTP Status codes

In our last segment, we discussed how to use Slim framework to build a RESTful api. I have introduced conventions and built an example of the required methods to define each of our CRUD (Create, Read, Update and Delete) actions. One thing missing from that example is HTTP status codes.

HTTP status codes are used by the server to communicate the result of the client initiated request. These codes are defined in the HTTP protocol.

For a web service, we don’t need to implement all of these status codes in order to make it functional. As defined in Part 1 of the tutorial, here is the most used status codes, I have added which action is most likely to use each code

HTTP Status codes
CodeMeaningUsed by ActionWhat does it mean
200OKRead, Update, DeleteAction executed successfully
201CreatedCreateResource was created successfully
304Not ModifiedUpdateResource wasn't updated
400Bad RequestAll ActionsAction is missing one or more parameters
401UnauthorizedAll ActionsCurrent client isn't authorized to perform action
403ForbiddenAll ActionsAction isn't allowed on resource
404Not FoundReadResource not existent
500Internal Server ErrorAll ActionsServer error, any other type of error

In PHP, we use http_response_code function to setup request’s status code. Here is how to use it:

<?php 
http_response_code(404); 
?>

That’s it, with this final piece of the puzzle, we are now ready to set forth and design the web’s future services with ease!

But before you head out, there are a few points I would like you to consider.

Considerations

In developing many web services, I have come up with a list of considerations that someone else might find useful. They are not mandatory practices, but I find web services have better chance to grow and develop having these considerations from the get go.

#1 SSL everywhere

Putting all the recent Heartbleed issues aside, I find the best way to protect your API is by using SSL encryption. Moving your Web services to SSL protects it from reverse engineering. When SSL is enabled, everything in the communication between the server and the client is encrypted (except for a few fields like URL and some headers). If you are developing a proprietary RESTful api, you can not go wrong with this one.

Even if your API is supposed to be public, having SSL encryption protects API access keys used by registered developers in order to prevent unauthorized communication and data manipulations. Which brings us to the second item of this considerations list.

#2 Access keys (or tokens)

Access keys are used to restrict access to your API. Defining an access key for every developer that uses your API is paramount to protect the server from unauthorized use.

Access keys are a sequence of random numbers and letters that is unique for each developer.

Usually, when a developer is using your API, his Access key is sent in the header of the request, or as a parameter to the service’s URL request. All your API calls must make sure that the provided Access Key query is valid and has authorization. Combining this consideration with SSL everywhere item mentioned above, will guarantee that no unauthorized developer can access your precious API without a valid Access key.

Let us see what this means. This can best be explained with 3 scenarios:

Scenario #1: Let us say you develop the best web service out there, and you have published your API documentation to the internet. At this point, anyone with access to your documentation can use your WebService. Handing out Access Keys to your developers ensures that you know who the developer is (which limits risk of abuse) and gives you the option to cut-off any developer that is misbehaving. This effectively protects you API and gives you the option to revoke specific developer access to the API.

Scenario #2: You decide to sell access to your API on a monthly subscription. One developer has failed to pay his dues. Having an access key gives you the opportunity and flexibility to enable and disable the offending developer’s access to your API.

Scenario #3: You have a mobile app that communicates with your web service. You do not want any unauthorized access to your private API other than through your app. Having an Access key again makes sure that only your app is able to communicate with your server using the private API.

With this I hope it is clear that your API must always have an Access key.

#3 Rate Limiting

Finally, the last of my humble considerations is rate limiting. When a web service is put online, there is no telling how many requests your server will handle. By combining the Access key consideration mention above and proper resource planing and load balancing, we must put a limit on the number of API call each Developer is allowed to do.

Putting a limit on the number of API calls per developer ensures that your service doesn’t buckle under pressure from its users. It also ensures a fair and equitable use of your web service by all of your registered users.

Therefore, any successful web service with a lot of developers must have a mechanism to limit the rate (or frequency) each developer’s API calls.

Conclusion

This concludes part 3 of “Web services by example” tutorial series. Other parts of this tutorial can be found Part1 and Part2. If you have comments or remarks, please do not hesitate to comment below.

If there is another subject you would like me to cover, follow me on twitter and let me know @mikeMTOL