In this new series, I plan on creating a collection of guides that will demonstrate how to create the same basic REST API in different programming languages.

As some of you who know me may know, I am very passionate about programming. I love learning a new language and comparing it to languages that I have already picked up. I am not entirely sure why I like so many different languages and I cannot, in all seriousness, an answer which is my favorite language suffices to say I am enamored with all aspects of programming in general.

Now with that being said, one of the best ways that I learn to pick up a new language, is to dive in and create something that I created before in a different language, sort of like the premise of creating the hello world application that most books start with, however I feel that approach is too simplistic of an example, so I decided to create this series of creating a basic REST API. This will be more so for my personal reference as are all the blog post that I write but maybe this can also become somewhat of a Rosetta Stone for someone else trying to pick up a new language as well.

The first guide that I will create will deal with languages that I already have experience with just to get me into the flow of creating the guides. The follow-up guides will be for languages that are new to me. If there are any requests for a particular guide, then I will be happy to do those as well. Also, I welcome any comments in which the guides can be improved.

{% include toc.html %}

**Disclaimer: ** I do not claim to be an expert on REST, APIs, or for that matter in all the languages that I am going to try and cover. As such, please do not regard these as best practices but rather a stepping stone on yours (and mine) path of learning.

With all of that out of the way, let’s say we get on with the guide. In this introduction, I am just going to cover the basics questions.

  1. What is an API?
  2. Examples of a Web API
  3. HTTP Methods and HTTP Status Codes
  4. What is REST?
  5. Examples of REST

What is an API?

An API or Application Programming Interface can be defined as a contract (or interface) in which other applications utilize to interact with your system. In doing so, this provides externally exposed features into your rather closed environment.

For this simplistic categorization of APIs, we can think of them coming in two flavors, one being software APIs and the other being web APIs. The focus of this series will be REST APIs which is a type of Web APIs.

Software APIs typically are related to software libraries or frameworks and are geared more towards desktop or client/server type applications.

Web APIs on the other hand deal with HTTP (Hypertext Transfer Protocol) methods and HTTP Status Codes. More on those later, but the methods are the actions which typically control the API and the status codes along with a response message is the result of what the API passes back.

Examples of a Web API

Many of the most popular websites have published public APIs these days. Not all of these examples are of REST APIs as well as the ones that do include REST API they also include other types of APIs like SOAP. Some examples of these popular APIs are:

  1. Google API

– Allows you to integration with maps, email, Google+, and more.
2. Facebook API
– Provides integrations like the ability to ‘Like’ and share pages from your website.
3. Twitter API
– With this integration, you can automate sending tweets when different events occur as well as read tweets via the API
– Allows you to access information about your contacts, send messages, among other things
5. LinkedIn API
– Allows you to perform searches, share content, etc.
6. Github API
– Provides the ability to create and search for Issues, Gists, Git Data, People, as well as a host of other features

HTTP Methods and HTTP Status Codes

HTTP Methods

HTTP methods are defined in the RFC 2616 put out by the World Wide Web Consortium (W3C). These HTTP methods are commonly referred to as “verbs”. Currently, there is a total of eight different verbs that are defined by the HTTP/1.1 protocol. Below these verbs are defined as well as their typical usage.


– Used to request what options are available for the request/response
2. GET
– Used to retrieve information about a resource
– Same as GET except for only returns the header information
– Used for creating a new resource
5. PUT
– Used for updating a resource
– Used for deleting a resource
– Used for tracing the request message
– Used for proxies

In a typical REST API we usually only concern ourselves with GET, POST, PUT, DELETE, which form the basis of CRUD (Create, Read, Update, and Delete). The most commonly used HTTP method that most people unknowingly utilize is the GET verb. Since GET is used as a way to retrieve information about a resource, which is what is used to load web pages into a browser. Have you ever filled out an online form? Then you have most likely used POST, though there are other options as well. Some browsers do not implement all the HTTP methods nor do they need to.

HTTP Status Codes

HTTP Status Codes are also defined in the RFC 2616 put out by the W3C. There are numerous types of status codes so for further information, please refer to section ten of the RFC. I will name a few that you are most likely to use the most, though they all have recommended use cases that are associated with them.

  1. Successful Codes – 2xx

– 200 – OK
– Request has succeeded
– 201 – Created
* New resource has been created
– 204 – No Content
* Request has been accepted
2. Redirect Codes – 3xx
– 304 – Not Modified
* Indicates resource has not been modified since last requested
3. Client Error Codes – 4xx
– 400 – Bad Request
– Request could not be understood
– 401 – Unauthorized
* Missing or invalid authentication information
– 403 – Forbidden
* User is not authorized to perform the operation or resource is unavailable
– 404 – Not Found
* Requested resource was not found
– 409 – Conflict
* A resource conflict
4. Server Error Codes – 5xx
– 500 – Internal Server Error
* General catch-all for thrown exceptions
– 503 – Service Unavailable
* Service cannot be used at the time of the request

What is REST?

REST stands for Representational State Transfer. For the best understanding of the REST architecture, I would refer to the man who came up with the idea, Roy Thomas Fielding. In his dissertation1,Architectural Styles and the Design of Network-based Software Architectures, details on REST can be found in chapter 5.

REST works on the basic principle of resources. A resource can be anything from a person to a task, to a blog post. While REST does not have an official standard that must be followed there are best practices and recommendations put forth in the dissertations and the RFC, amongst other places on the internet. I will not attempt to set for any of those in these guides as I am just trying to show the basic functionality of REST APIs in implemented in different languages. Even though there isn’t a set standard, there are six defined constraints that attempt to define what exactly makes a RESTful API.

The six constraints are:

  1. Client-Server

– This one deals with the separation of concern between the client and server. If the interface between the two remains unchanged, then the client and/or server can be replaced and developed independently of each other.
2. Stateless
– By definition, REST means statelessness; therefore the state is handling the request is embedded in the request itself.
3. Cache
– This one states that a resource must be cacheable and define themselves as such to the client.
4. Uniform Interface
– This one defines the interface between the client and server that allows the two to be decoupled from each other. Uniform Interface can be further described by four interface constraints:
1. Identification of Resources
– Resources are identified in requests using URIs
2. Manipulation of Resources through Representations
– Providing you have permission to, you should have enough information to modify or delete a resource once given the representation of the resource
3. Self-descriptive messages
– States that each request/response describes how to process each message
4. Hypermedia as the engine of application state (HATEOAS)
– HATEOAS states that the client should be able to interact with the service entirely through hypermedia.
5. Layered System
– The system should be composed of hierarchical layers by constraining component behavior such that each component cannot interact with any layer beyond the immediate layer with which they are interacting with. So, the client would not be able to interact directly with the end server if there is a cache server in between them. The client would interact with the cache server which would, in turn, interact with the server.
6. Code-On-Demand (Optional)
– This states that additional functionality can be distributed in the form of scripts through the API.

Examples of REST

The remaining guides will cover the creation of a task list REST web service. Here we will look at a few examples that will utilize the task list example.

If we wanted to get a list of all task, we would utilize the GET HTTP method:


Say we wanted to create a new task, for that we would utilize the POST HTTP method:


<!--?xml version="1.0"?-->

Some Name Here

If there is a specific task that you would like to see, we will use GET like above and provide it with the task_number:


To update the name of the task that we just retrieve we would use the PUT verb and could do something like:


<!--?xml version="1.0"?-->

New Name Here

And assuming we had permission to do so, we can delete it by, you guessed it, the DELETE method:


For further examples, follow along with the rest of the series and see how we go about implementing a basic REST API for tasks, and then take it a step further and see how do implement the same API across different languages.


  1. Fielding, Roy Thomas. Architectural Styles and the Design of Network-based Software Architectures. Doctoral dissertation, University of California, Irvine, 2000.