I did this project while in training at my first programming job, and cleaned it up and made it more RESTful in training at my second job. Its purpose was to help me begin to understand how to use apis to get data from the web and use it in an application. It obviously is not the best way to do what it does, but it was a fun little project.
You can run it using mvn spring-boot:run
when in the root directory, and hit the service at localhost:8080.
REST stands for Representational State Transfer, and is an architectural style used for representing resources, and whose methods roughly align with CRUD. REST is based on getting data on and performing operations on data, using URIs where the path indicates the resource, and the HTTP verb (GET, POST, etc.) indicates the action.
SOAP and RPC (Simple Object Access Protocol and Remote Procedure Call, respectively) are protocols for calling methods on servers. The path in the URI will indicate the action being taken, and any relevant data will be included in the request body or in query parameters.
- A RESTful service should have a clearly defined client-server relationship, so that server logic and client logic can be easily separated.
- A RESTful service should be stateless - each request should be self contained, and have enough information for the server to be able to understand it and fulfill it.
- A RESTful service should be, in part, cacheable. Responses to idempotent requests should declare themselves cacheable, so that the client or a layer in front of the server can cache them.
- A RESTful service should use HATEOAS (Hypermedia As The Engine Of Application State), that is, the service should send with any responses to the clients descriptions of other, related resources the client can call methods on.
- A RESTful service can be easily modified without needing to inform or update the clients. Thanks to HATEOAS, consumers of the service can be made to be adaptable to any changes on the server.
- REST aims to intuitively represent a set of resources and actions available on them
Hypermedia in this context refers to the practice in REST of including links to related resources in responses from the server, so that a client can, with no prior knowledge except the base entry point, effectively take advantage of all the methods exposed by the RESTful service. Using hypermedia is good practice because it allows consumers of the service to be adaptable, and it decouples the client logic and the server logic.
REST can be used with protocols besides HTTP, but it is most commonly used with HTTP.
As REST is used to represent resources and actions that can be taken on them, many different actions can be triggered with the same URL, depending on the HTTP method used. A GET would get information about a resource, a POST would likely create a new resource, and possibly trigger an event associated with that resource, a PUT or PATCH would typically update an existing resource, and a DELETE would delete a specific resource.
The HTTP status codes are also useful in the implementation of RESTful services. Oftentimes just a status code is sufficient to communicate the requested information to a client, so a response body is not necessary.
The benefit of using REST with HTTP is that we don't have to reinvent the wheel - HTTP already has in place many features which can be used to create an intuitive RESTful web service.
Enunciate is helpful in building documentation for Java web services, and for generating client side libraries in various libraries
JAX-RS is important in that it provides annotations for declaring the context of methods and parameters of Java classes that will be deployed as web servers. It has headers for each of the method types, for defining a path, for declaring content types, and for binding http parameters to Java method parameters.
JAXB is a library that can be used for serializing Java objects to an XML representation, and vice versa. This is significant in the prevalence of web services because it facilitates a standardized way in which clients and servers can communicate.
Jackson is a library that can be used for serializing Java objects to JSON, and vice versa.
Both JAXB and Jackson have annotations that allow fine grained control over serialization and deserialization, and may be set up on a server to automatically serialize responses and deserialize requests.