This document discusses best practices for building RESTful APIs. It defines REST as relying on a stateless, client-server architecture using HTTP. It recommends using URL paths and HTTP methods like GET, POST, PUT, DELETE to describe APIs and provide examples. General rules are outlined for handling collections of resources vs individual resources. Spring REST controllers are demonstrated. Documentation of REST APIs using Swagger is also covered, including annotations for describing endpoints, operations, and responses.

1. Building RESTful APIs
best practices by Ania Pietras

2. What is REST?
REST stands for Representational State Transfer. (It is sometimes spelled
"ReST".) It relies on a stateless, client-server, cacheable communications
protocol -- and in virtually all cases, the HTTP protocol is used.
SOAP REST
More about REST: http://www.restapitutorial.com/lessons/whatisrest.html

3. REST
URL
HTTP METHOD
HEADER
BODY

4. USE URL + HTTP METHOD TO
DESCRIBE YOUR API

5. URL examples
Some GET methods:
www.coolstuff.com/shop - show whole shop
www.coolstuff.com/shop/awesomeThings - show products
from category awesomeThings
www.coolstuff.com/shop/awesomeThings/123 - show details
about awesome things with 123 as ID
www.coolstuff.com/shop/cart - show your cart
www.coolstuff.com/shop/cart/1 -show the first item of your cart
POST method:
www.coolstuff.com/shop/cart + JSON - add awesomeThing
with ID 123 to your cart
DELETE method:
www.coolstuff.com/shop/cart/1 - delete the first item of your
cart

6. General Rules
for entire collection:
/awesomeThings
for given item:
/awesomeThings/{id}
we control actions by using specific http method

7. POST Creates a new resource. 201 (Created), 'Location' header
with link to /customers/{id}
containing new ID.
404 (Not Found), 409 (Conflict) if
resource already exists..
PUT Updates an existing
resource.
404 (Not Found), unless you want
to update/replace every resource
in the entire collection.
200 (OK) or 204 (No Content).
404 (Not Found), if ID not found or
invalid
DELETE Deletes a resource. 404 (Not Found), unless you want
to delete the whole collection—not
often desirable.
200 (OK). 404 (Not Found), if ID
not found or invalid.
EDIT Retrieves a resource. 200 (OK), list of customers. Use
pagination, sorting and filtering to
navigate big lists.
200 (OK), single customer. 404
(Not Found), if ID not found or
invalid.
HTTP methods
Entire Collection (e.g. /customers) Specific Item (e.g. /customers/{id})

8. RESTful Controller in Spring application
@RestController
public class GreetingController {
...
@RequestMapping(value="/hello", method=RequestMethod.GET)
@ResponseStatus(HttpStatus.OK)
public boolean sayHello() {
return helloService.sayHello()
}
@RequestMapping(value="/hello", method=RequestMethod.GET)
@ResponseStatus(HttpStatus.OK)
public boolean sayPersonalizedHello(@RequestParam("name") String name) {
return helloService.sayPersonalizedHello(name)
}
}
@RequestMapping(value="/hello/{nickId}", method=RequestMethod.GET)
@ResponseStatus(HttpStatus.OK)
public boolean sayBroHello(@PathVariable(“nickId”) Long nickId) {
return helloService.sayBroHello(nickId)
}
}
use when you pass id
@RestController = @Controller + @ResponseBody
use when you pass something more complex
than id

9. Documenting REST API with Swagger
/**
* REST endpoint
*/
@Api(value = "users", description = "Endpoint for user management")
@Path("/users")
public class UsersEndpoint {
...
}

10. Documenting REST API with Swagger
@GET
@Path("/{userName}")
@Produces(MediaType.APPLICATION_JSON)
@ApiOperation(value = "Returns user details", notes = "Returns a complete list of users details with date of last modification.",
response = User.class)
@ApiResponses(value = {
@ApiResponse(code = 200, message = "Successful retrieval of user detail", response = User.class),
@ApiResponse(code = 404, message = "User does not exist"),
@ApiResponse(code = 500, message = "Internal server error")}
)
public Response getUser(@ApiParam(name = "userName", value = "Alphanumeric login to the application", required = true) @PathParam
("userName") String userName) {
...
}

11. Read more:
http://www.restapitutorial.com/lessons/whatisrest.html
https://codeplanet.io/principles-good-restful-api-design/
http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api