RESTful web services are built to work best on the Web (REST: Representational State Transfer). REST is an architectural style that specifies constraints such as uniform interface and enable services to work best on the Web. In REST architecture, data and functionality are considered resources, and accessed them by using Uniform Resource Identifiers (URIs). There are some motivations of using RESTful Web Services:
The objective of this tutorial is to help you to get familiar with programming APIs, especially understand the idea of microservices architecture.
The examples discussed in this tutorial were programmed using the following software and tools:
We first need to configure Apache Tomcat by extracting it to your local disk after downloading the source file. We note that the path to Apache Tomcat directory should not contain any whitespace or special characters. Then, you should follow the steps below to configure Apache Tomcat in Eclipse IDE:
In this first example, we will show you how to program an API with GET method. We note that GET method is a kind of HTTP request methods to indicate the desired action to be performed for a given resource. Before beginning, we need to configure the project as follows:
com.soa.computingand a Calculator.java class, as shown in Fig. 6. According to the Oracle documentation, the
@Pathannotation identifies the URI path template to which the resource responds, and is specified at the class level of a resource. The
@Pathannotation's value is a partial URI path template relative to the base URI of the server on which the resource is deployed, the context root of the WAR, and the URL pattern to which the Jersey helper servlet responds. URI path templates are URIs with variables embedded within the URI syntax. These variables are substituted at runtime in order for a resource to respond to a request based on the substituted URI. Variables are denoted by curly braces. To obtain the value of the username variable, the
@PathParamannotation may be used on the method parameter of a request method.
@GETmethod whose aim is to request a representation of the specified resource. In this section, we implement a
@POSTmethod to submits an entity to the specified resource, often causing a change in state or side effects on the server.
@POSTmethod, we need to implement a Student.java class that represents a Student object in real-world. We assume a Student has four properties, i.e.,
major:String, as shown in below figure.
@POSTmethod in Calculator.java, as shown in below figure. You can implement this method in another class. There are two nothworthy points in this method:
@Consumesannotation is used to specify which MIME media types of representations a resource can accept, or consume, from the client. If
@Consumesis applied at the class level, all the response methods accept the specified MIME types by default. If applied at the method level,
@Consumesannotations applied at the class level. If a resource is unable to consume the MIME type of a client request, the JAX-RS runtime sends back an HTTP 415 ("Unsupported Media Type") error. The value of
@Consumesis an array of String of acceptable MIME types such as
Studentobject that send from a client, and the question here is how this method can map an JSON object from client to a Java object (
Student). POJO suppport represents the easiest way to convert your Java Objects to JSON and back which is based on the Jackson library. To use this approach, you will need to turn the
JSONConfiguration.FEATURE_POJO_MAPPINGfeature on which could be done in web.xml using the following servlet init parameter, as shown in below figure. For further reading, you can refer to this article to learn more about Jersey JSON.
@POSTAPI, we need to use Postman software with the configurations as shown in below figure. After submitting the request, the API will (1) return a message to client to inform the results, and (2) print the
Studentobject on server's console window.
GetDateTimefrom the sample project, you are required to modify this method that allows a client passes location information as a parameter such as
Europe/Bucharest, then the method return the current date-and-time of the given location. To implement this methods, you can take advantage of Joda-Time library which has been already bundled as presented in Resources section.
idof a student and returns TRUE/FALSE where TRUE indicates the given
idexists in the database, and vice versa. To implement this method, you do not need to construct a database, just declare an array/list of students.
public Response changeGender(int id, int gender)method does change the
genderproperty of a student to the new one based on the given
idinformation; then, the method returns HTTP response status codes to inform the results.
Responseobjects, you are required to modify the previous methods to make them return JSON objects. For example,
public boolean searchStudentById(String id)method is changed to
public Student searchStudentById(String id)to return a JSON object that represents a student, otherwise, return
NULLor a dumb object. You can read this article to know how to convert a Java object to/from JSON object by using Jackson 2 library.
SEVERE: Servlet [Jersey REST Service] in web application [PROJECT_NAME] threw load() exception java.lang.IllegalArgumentException: Unsupported class file major version 59, as shown in Fig. 16a, you should change Java Compiler version from 17 to 1.7 by performing the following steps: Right-click on project name → Properties → Java Compiler → Uncheck the Use compliance from execution environment 'JavaSE-17' on the 'Java Build Path' option → Select 1.7 from the drop-down list of Compiler compliance level → Then, click Apply and Close button to save the changes.
404 - Page Not Founderror — When you run your project on Apache Tomcat server, it will automatically open the default webpage (
index.html). By default, the
index.htmlfile is absent, it will thus return the
404 - Page Not Founderror code, as shown in Fig. 17. To address this problem, we just create an
src/main/webapp/directory. For example, the content of
index.htmlfile is presented in Fig. 18.
EXC_CRASH (Code Signature Invalid), as shown in Fig. 23, you need to execute the
codesign --force --deep --sign - /Applications/Eclipse.appcommand in Terminal. You should note that the Eclipse application must be placed in /Applications directory before executing the command.