REST Service

REST and CRUD operations

One of the key principles of REST is the use of standard HTTP methods to perform CRUD (Create, Read, Update, Delete) operations on resources. Here's how the HTTP methods are typically mapped to CRUD operations:

HTTP action CRUD operation description example response
GET Read used to retrieve resource representations or collections of resources. It's commonly used to fetch data from the server without modifying it GET /books: Retrieve a list of all books.
GET /books/{id}: Retrieve details of a specific book.
200 OK + resource in the message body
404 Not Found if the resource was not found
POST Create used to create new resources. When you send a POST request, you typically include data in the request body, which the server then processes to create a new resource. POST /books: Create a new book (usually returns the id of the created resource). 201 Created + Location header giving the url of the newly created resource
sometimes the message body includes the description of the newly created resource
PUT Update used to update existing resources (or create, but it's not common) a new resource if it doesn't exist. When you send a PUT request, you typically include the complete representation of the resource you're updating. PUT /books/{id} (+body part): : Update a specific book 200 OK and the message body contains the description of the updated resource
204 No Content and the message body is empty
404 Not Found if the resource does not exist (except when PUT is accepted to create a new resource)
PATCH Partial Update used to apply partial modifications to a resource. It's typically used when you want to update only specific fields of a resource, rather than the entire representation. PATCH /books/{id} (+body part): : Update specific fields of a specific book 200 OK and the message body contains the description of the updated resource
204 No Content and the message body is empty
404 Not Found if the resource does not exist
DELETE Delete used to remove a resource from the server. When you send a DELETE request, the server deletes the specified resource. DELETE /books/{id}: Delete a specific book 204 No Content
more rarely: 200 OK

Getting started with RESTer

When you type an url in the address bar of a web browser, the browser sends a GET request. For your browser to send POST or DELETE requests for instance, you need some code embedded in a web form, usually triggered when you click a button. You can also use a browser extension to send custom requests such as the RESTer add-on.

Check at the RESTer extension is installed (if not, install it) and open it: click on the Extensions icon Firefox Extensions icon and next on the RESTer icon RESTer icon.

To try a GET request using RESTer, use the url api.chucknorris.io/jokes/random you're already familiar with:
screenshot of a GET request with RESTer

To gain some experience with the other operations, we need a different service (ChuckNorris only serves GET requests). Multiple testing services are available such as JSONPlaceholder (our choice), ReqRes, mockapi.io, RESTful-Booker, Postman mock server and SoapUI (great tools, but a bit too complex to start with for our needs)...

  1. Get the list of all posts
  2. Get only the post of id 3
  3. Try to get the post of id 333 (that does not exist)
  4. Get the comments on post 3 (2 different routes)
  5. Create a new post:
    It requires to change the HTTP method to POST
    It requires to provide a body ("BODY" tab):
    {
        "userId": 1,
        "title": "post request example",
        "body": "Hoc est brevis textus nihilominus."
    }

    And it requires to add a header: Name = Content-Type, Value = application/json
    In response you get the id of the new post (101). But since this is a mock service open to anyone, it is a fake addition: if you list all posts again it won't be listed.
  6. Change the title of post 3 (again, your change won't be written to the server but you get a response as if it had)
  7. Delete post 3

When you click the button "More options" with 3 dots at the top right corner, you can ask RESTer to show the curl command. "-X" is used to indicate the HTTP method when it's not the default "GET". "-H" is used to set headers and "-d" to set the data (body) part.

curl http://jsonplaceholder.typicode.com/posts
curl http://jsonplaceholder.typicode.com/posts/3
curl http://jsonplaceholder.typicode.com/posts/333  

curl http://jsonplaceholder.typicode.com/posts/3/comments 
curl 'http://jsonplaceholder.typicode.com/comments?postId=3'

curl -X POST http://jsonplaceholder.typicode.com/posts \
    -H 'Content-Type: application/json' \
    -d '{
    "userId": 1,
    "title": "post request example",
    "body": "Hoc est brevis textus nihilominus."
}'

curl -X PUT http://jsonplaceholder.typicode.com/posts/3 \
    -H 'Content-Type: application/json' \
    -d '{
    "userId": 1,
    "id": 3,
    "title": "new title",
    "body": "et iusto sed quo iure\nvoluptatem occaecati omnis eligendi aut ad\nvoluptatem doloribus vel accusantium quis pariatur\nmolestiae porro eius odio et labore et velit aut"
}'

curl -X PATCH http://jsonplaceholder.typicode.com/posts/3 \
    -H 'Content-Type: application/json' \
    -d '{
    "title": "new title"
}'

curl -X DELETE http://jsonplaceholder.typicode.com/posts/3