01.JAX RS Configuration - JohnyzHub/jax-rs GitHub Wiki

RESTful web services are a popular architectural style for designing networked applications that utilize the principles of Representational State Transfer (REST). They allow different applications or services to communicate over the web using a set of predefined rules and conventions. Below is a detailed explanation of RESTful web services:

1. Client-Server Separation: REST separates the user interface concerns from the data storage concerns. This separation allows the client and server to evolve independently. For example, a mobile application (client) can interact with a RESTful API (server) and can be updated without impacting the server.

2. Uniform Interface: RESTful architecture is defined by a uniform interface that simplifies communication between the client and the server. This minimizes the number of assumptions and dependencies on how the requests and responses should be structured. Key constraints of this interface include:

   • Identification of resources through URIs (Uniform Resource Identifiers).
   • Standardized methods (HTTP verbs) for interacting with resources (GET, POST, PUT, DELETE).
   • Resource representations, which can be in various formats (JSON, XML, HTML, etc.).

3. Statelessness: Each request from a client to a server must contain all the information needed to understand and process the request. The server does not store any state about the client session. This allows for scalability and reliability since any server can handle any request from any client.

4. Cacheability: Responses from the server can be explicitly marked as cacheable or non-cacheable. If a response is cacheable, clients can store and reuse it for future requests, thereby improving performance and reducing server load.

5. Layered System: A RESTful architecture can be composed of multiple layers, each with its functionality. For example, a client might interact with a proxy or load balancer, which interacts with the actual server. This abstraction allows for scalability and modularity.

6. Code on Demand (optional): Servers can extend client functionality by transferring executable code (like JavaScript). This is optional and not employed in all RESTful APIs.

Typically, RESTful APIs expose a set of endpoints (URIs) that represent resources, and clients interact with these resources using standard HTTP methods:

• GET: Retrieve data from a server.
• POST: Send data to a server to create a new resource.
• PUT: Update an existing resource on the server.
• DELETE: Remove a resource from the server.

The following table lists HTTP request methods and their categorization in terms of safety, idempotency.

refer this weblink for additional details: http-methods

In REST, resources are the fundamental concepts that you interact with. A resource can be anything (e.g., users, orders, products). Each resource is uniquely identified by a URI.

For example:

• /users might represent a collection of user resources.
• /users/123 could represent a specific user with the ID 123.

Interactions with these resources occur through representations, which are typically formatted as JSON or XML. For instance, a GET request to /users/123 may return a JSON representation of the user, including attributes like name, email, and address.

HATEOAS is a constraint of the REST application architecture that allows clients to navigate an API by following links provided in the responses, rather than predefined URLs. This means that a client can dynamically discover actions on resources by examining their representations. For example, a response representing a user may include links to update or delete that user.

HTTP status codes are used to indicate the outcome of RESTful requests. Common status codes include:

• 200 OK: The request was successful.
• 201 Created: A new resource was created as a result of the POST request.
• 204 No Content: The request was successful, but there is no content to send back (often used for DELETE).
• 400 Bad Request: The request could not be understood or was missing required parameters.
• 404 Not Found: The requested resource does not exist.
• 500 Internal Server Error: An error occurred on the server while processing the request.

• Simplicity: The use of standard HTTP protocols and methods makes REST simple to understand and use.
• Scalability: Statelessness helps improve scalability because any server can handle any request at any time.
• Interoperability: RESTful web services can be consumed by clients built with different technologies and languages, as they communicate over standard HTTP.
• Flexibility: Support for multiple representation formats allows clients to choose how they want to receive the data.

javax.ws.rs.core.Application is a deployment agnostic abstract class provided by JAX-RS for configuring and registering the components of a JAX-RS application and it's also used to supply additional metadata to the application. Application subclasses can be annotated with @ApplicationPath, defining the base URI for the JAX-RS resource classes (classes annotated with @Path). Application subclasses are instantiated once when the web application starts and they are managed by the JAX-RS runtime.
If no resource classes or providers are registered, the JAX-RS runtime will scan the classpath for JAX-RS components and will register them automatically. But registering the required resources manually is strongly encouraged.

This sample application moviedirectory has covered the below features

• Exception-Handling
• server sent events
• caching techniques
• asynchronous service
• filters-and-Interceptors
• Deploying war file directly to the autodeploy folder of the application server.
• Mapping JSON to the POJO in the restful request using 'jersey-media-moxy' jar.

To list the documentation of this service:

deploy the service to any application server such as payara and access: http://localhost:8080/openapi

   Base URI      : http://localhost:8080/moviedirectory/rest
   Resource Path : directory

   Rest end points: 

    GET:   http://localhost:8080/moviedirectory/rest/directory
             Headers:content-type - application/json

    POST: http://localhost:8080/moviedirectory/rest/directory/movie
             Headers:content-type - application/json
             Body: {
                    	"number":"3",
                    	"title":"Matrix"
                   }

    PUT: http://localhost:8080/moviedirectory/rest/directory/movie
             Headers:content-type - application/json
             Body: {
                    	"number":"3",
                    	"title":"Matrix-Reloaded"
                   }

    GET: http://localhost:8080/moviedirectory/rest/directory/price/0
             Headers:content-type - application/json