Routings and Simple Guide to Create RESTful API

What is RESTful API?

RESTful API describes a kind of web architecture design (but not limited to web application). Usually, we use the HTTP protocol provided verbs and mapped to the CRUD (Create, Read, Update, Delete) operations with respect to the database. If you are familiar with this, you can skip to the example code below. If you are more interested on how and why it is defined like this, you can consult on several resources which is listed below:

GET Action

The GET action represents client-side request content from the server-side, it is similar to the read action.

Assume that the example URL is https://example.com/articles/ , we expected that it will show all of the article records in HTTP status 200. That is, query all of the article data (or read the article data) from the database and render out HTML or other kinds of format according to the request Content-Type header. Otherwise, if the resource is not found, then it should return status 404.

Another example URL is https://example.com/articles/12/, we expected that it will show us the 12th article record in HTTP status 200. That is, we will specifically query the article data where its id = 12 from the database. Otherwise, same as the example above, if the resource is not found, or record with id = 12 is not existed, it should return status 404.

Route design like:

  • https://example.com/showArticles?title=Greetings (Is this route showing all of the articles or only article with specified topic?)
  • https://example.com/articles?id=3
  • https://example.com/showArticle/3 (Name of the route with verb)
  • https://example.com/showArticle?id=3

are not RESTful, it should be something like:

  • https://example.com/articles/ with GET action request (Show all of the articles)
  • https://example.com/articles/3 with GET action request (Show the 3rd record of the articles )

POST Action

The POST action represents form data sent from the client-side to the server-side, it is similar to the create action. Assume that we are already in the URL https://example.com/articles/new which we can create a new article and we submit our form data with JSON format {"title": "Greetings", "content": "Hello World"} through POST request to server. Server then create a new article record according to the content of JSON data and save it to the database.

Route design like https://example.com/createArticle is not RESTful, it should be simple like:

  • https://example.com/articles/ with form data (which is the request body) and POST action request

which already tells the server that I wanted to create a new article with the data specified in the request body.

PUT Action

The PUT action represents update the whole record of the data. Assume that we want to modify the 5th article which the JSON format of the form data is:

{ title: "RESTful API", content: "Use Goby to Implement!" }

Instead using the non-RESTful format of the request which is something like:

  • https://example.com/modifyArticle?id=5 with request body as the JSON form data and POST action request

We can use

  • https://example.com/articles/5 with form data and PUT action request

which is similar to telling the server that I wanted to change the data of the 5th article with the form data specified in the request body instead of using the plain POST request with ugly routing format.

PATCH Action

The PATCH action is similar to the PUT action, it also update the record but we just update the part we need instead of all of the record. Assume that we wanted to change the title of the 7th article - Introducing Ruby into:

{ title: "Introducing Goby" }

Instead of using non-RESTful format of the request:

  • https://example.com/modifyArticle?id=7 with form data and POST action request

or worse...

  • https://example.com/changeArticleTitle?id=7

We can change it to simple RESTful route:

  • https://example.com/articles/7 with form data and PATCH action request

which already tells server that I wanted to change the 7th article with the data according to the request body

DELETE Action

The DELETE action, namely, delete the record from database. Assume we wanted to delete the 10th article. We might do something like:

  • https://example.com/deleteArticle with POST request that deletes the 10th article

but we can also choose a more concise format which is RESTful:

  • https://example.com/articles/10 with DELETE action request

RESTful Routes Implementation

Basic infrastructure of the RESTful route is represented below:

require 'net/simple_server'

# Create a new server instance
server = Net::SimpleServer.new(3000)

# Root path
server.get("/") do |req, res|
  res.status = 200
  res.body   = "Hello World!"
  res.set_header("Content-Type", "text/html; charset=utf-8")
end

# GET all of the articles Action
server.get('/articles') do |req, res|
  # ...
end

# POST create an new article Action
server.post('/articles') do |req, res|
  # ...
end

# PUT update an article Action
server.put('/articles/{id:[0-9]+}') do |req, res|
  # ...
end

# DELETE delete an article Action
server.delete('/articles/{id:[0-9]+}') do |req, res|
  # ...
end

# Start out the server
server.start

More content coming soon...

results matching ""

    No results matching ""