0
# JAX-RS API
1

2
JAX-RS (Java API for RESTful Web Services) is the Java EE standard specification for building RESTful web services. It provides annotations, interfaces, and utilities for creating both server-side REST endpoints and client-side REST consumers with support for content negotiation, parameter injection, asynchronous processing, and modern features like Server-Sent Events.
3

4
## Package Information
5

6
- **Package Name**: javax.ws.rs:javax.ws.rs-api
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: `<dependency><groupId>javax.ws.rs</groupId><artifactId>javax.ws.rs-api</artifactId><version>2.1.1</version></dependency>`
10

11
## Core Imports
12

13
```java
14
// Core annotations for REST endpoints
15
import javax.ws.rs.GET;
16
import javax.ws.rs.POST;
17
import javax.ws.rs.PUT;
18
import javax.ws.rs.DELETE;
19
import javax.ws.rs.PATCH;
20
import javax.ws.rs.Path;
21
import javax.ws.rs.PathParam;
22
import javax.ws.rs.QueryParam;
23
import javax.ws.rs.HeaderParam;
24
import javax.ws.rs.Produces;
25
import javax.ws.rs.Consumes;
26
import javax.ws.rs.DefaultValue;
27
import javax.ws.rs.BeanParam;
28

29
// Client API
30
import javax.ws.rs.client.Client;
31
import javax.ws.rs.client.ClientBuilder;
32
import javax.ws.rs.client.WebTarget;
33
import javax.ws.rs.client.Entity;
34

35
// Core types
36
import javax.ws.rs.core.Application;
37
import javax.ws.rs.core.Context;
38
import javax.ws.rs.core.UriInfo;
39
import javax.ws.rs.core.MediaType;
40
import javax.ws.rs.core.Response;
41
import javax.ws.rs.core.MultivaluedMap;
42

43
// Extensions and providers
44
import javax.ws.rs.ext.Provider;
45
import javax.ws.rs.ext.ExceptionMapper;
46

47
// Container and filters
48
import javax.ws.rs.container.ContainerRequestFilter;
49
import javax.ws.rs.container.ContainerResponseFilter;
50

51
// Server-sent events
52
import javax.ws.rs.sse.Sse;
53
import javax.ws.rs.sse.SseEventSink;
54
```
55

56
## Basic Usage
57

58
```java
59
// Simple REST resource
60
@Path("/users")
61
public class UserResource {
62
    
63
    @GET
64
    @Path("/{id}")
65
    @Produces(MediaType.APPLICATION_JSON)
66
    public Response getUser(@PathParam("id") String userId) {
67
        User user = findUser(userId);
68
        return Response.ok(user).build();
69
    }
70
    
71
    @POST
72
    @Consumes(MediaType.APPLICATION_JSON)
73
    @Produces(MediaType.APPLICATION_JSON)  
74
    public Response createUser(User user) {
75
        User created = saveUser(user);
76
        return Response.status(Response.Status.CREATED).entity(created).build();
77
    }
78
}
79

80
// Client usage
81
Client client = ClientBuilder.newClient();
82
WebTarget target = client.target("http://api.example.com/users/123");
83
Response response = target.request(MediaType.APPLICATION_JSON).get();
84
User user = response.readEntity(User.class);
85
```
86

87
## Architecture
88

89
JAX-RS follows a resource-oriented architecture with these key concepts:
90

91
- **Resources**: Java classes annotated with `@Path` that handle HTTP requests
92
- **Resource Methods**: Methods annotated with HTTP method annotations (`@GET`, `@POST`, etc.)
93
- **Parameter Injection**: Automatic binding of HTTP parameters to method parameters using annotations
94
- **Content Negotiation**: Automatic serialization/deserialization based on `@Produces` and `@Consumes`
95
- **Providers**: Extension points for custom serialization, exception handling, and request/response processing
96
- **Filters and Interceptors**: Cross-cutting concerns for authentication, logging, etc.
97

98
## Capabilities
99

100
### Resource Endpoints
101

102
Core annotations for defining REST endpoints, HTTP method mapping, and parameter injection.
103

104
```java { .api }
105
@Target({ElementType.TYPE, ElementType.METHOD})
106
@Path(String value);
107

108
// HTTP method annotations
109
@Target(ElementType.METHOD)
110
@GET;
111
@POST;
112
@PUT;
113
@DELETE;
114
@HEAD;
115
@OPTIONS;
116
@PATCH;
117

118
// Parameter injection annotations
119
@Target(ElementType.PARAMETER)
120
@PathParam(String value);
121
@QueryParam(String value);
122
@HeaderParam(String value);
123
@CookieParam(String value);
124
@FormParam(String value);
125
@MatrixParam(String value);
126
@BeanParam;
127
@DefaultValue(String value);
128

129
// Content negotiation
130
@Target({ElementType.TYPE, ElementType.METHOD})
131
@Consumes(String[] value);
132
@Produces(String[] value);
133

134
// Context injection
135
@Target(ElementType.PARAMETER)
136
@Context;
137
```
138

139
[Resource Endpoints](./resource-endpoints.md)
140

141
### Client API
142

143
Fluent API for consuming RESTful web services with support for synchronous, asynchronous, and reactive invocations.
144

145
```java { .api }
146
interface Client extends Configurable<Client>, AutoCloseable {
147
    WebTarget target(String uri);
148
    WebTarget target(URI uri);
149
    WebTarget target(UriBuilder uriBuilder);
150
    WebTarget target(Link link);
151
}
152

153
interface WebTarget extends Configurable<WebTarget> {
154
    URI getUri();
155
    UriBuilder getUriBuilder();
156
    WebTarget path(String path);
157
    WebTarget queryParam(String name, Object... values);
158
    Invocation.Builder request();
159
    Invocation.Builder request(String... acceptedResponseTypes);
160
    Invocation.Builder request(MediaType... acceptedResponseTypes);
161
}
162
```
163

164
[Client API](./client-api.md)
165

166
### Server Container
167

168
Server-side processing including filters, interceptors, asynchronous processing, and resource management.
169

170
```java { .api }
171
interface ContainerRequestFilter {
172
    void filter(ContainerRequestContext requestContext) throws IOException;
173
}
174

175
interface ContainerResponseFilter {
176
    void filter(ContainerRequestContext requestContext, 
177
                ContainerResponseContext responseContext) throws IOException;
178
}
179

180
interface AsyncResponse {
181
    boolean resume(Object response);
182
    boolean resume(Throwable response);
183
    boolean cancel();
184
    boolean cancel(int retryAfter);
185
    boolean cancel(Date retryAfter);
186
    boolean isSuspended();
187
    boolean isCancelled();
188
    boolean isDone();
189
    boolean setTimeout(long time, TimeUnit unit);
190
}
191
```
192

193
[Server Container](./server-container.md)
194

195
### Core Types
196

197
Essential JAX-RS types for HTTP handling, URI manipulation, media types, and response building.
198

199
```java { .api }
200
abstract class Response implements AutoCloseable {
201
    public static ResponseBuilder status(Status status);
202
    public static ResponseBuilder status(int status);
203
    public static ResponseBuilder ok();
204
    public static ResponseBuilder ok(Object entity);
205
    public static ResponseBuilder created(URI location);
206
    public static ResponseBuilder noContent();
207
    public static ResponseBuilder notModified();
208
    
209
    public abstract int getStatus();
210
    public abstract StatusType getStatusInfo();
211
    public abstract Object getEntity();
212
    public abstract <T> T readEntity(Class<T> entityType);
213
}
214

215
abstract class UriBuilder {
216
    public static UriBuilder newInstance();
217
    public static UriBuilder fromUri(String uri);
218
    public static UriBuilder fromUri(URI uri);
219
    
220
    public abstract UriBuilder path(String path);
221
    public abstract UriBuilder queryParam(String name, Object... values);
222
    public abstract URI build(Object... values);
223
}
224
```
225

226
[Core Types](./core-types.md)
227

228
### Extensions
229

230
Extension APIs including providers, message body readers/writers, exception mappers, and parameter converters.
231

232
```java { .api }
233
@Provider
234
interface MessageBodyReader<T> {
235
    boolean isReadable(Class<?> type, Type genericType, 
236
                      Annotation[] annotations, MediaType mediaType);
237
    T readFrom(Class<T> type, Type genericType, Annotation[] annotations,
238
              MediaType mediaType, MultivaluedMap<String, String> httpHeaders,
239
              InputStream entityStream) throws IOException, WebApplicationException;
240
}
241

242
@Provider  
243
interface MessageBodyWriter<T> {
244
    boolean isWriteable(Class<?> type, Type genericType,
245
                       Annotation[] annotations, MediaType mediaType);
246
    void writeTo(T t, Class<?> type, Type genericType, Annotation[] annotations,
247
                MediaType mediaType, MultivaluedMap<String, Object> httpHeaders,
248
                OutputStream entityStream) throws IOException, WebApplicationException;
249
}
250

251
@Provider
252
interface ExceptionMapper<E extends Throwable> {
253
    Response toResponse(E exception);
254
}
255
```
256

257
[Extensions](./extensions.md)
258

259
### Server-Sent Events
260

261
Modern Server-Sent Events (SSE) API for real-time server-to-client communication.
262

263
```java { .api }
264
interface Sse {
265
    OutboundSseEvent.Builder newEventBuilder();
266
    SseBroadcaster newBroadcaster();
267
}
268

269
interface SseEventSink extends AutoCloseable {
270
    CompletionStage<?> send(OutboundSseEvent event);
271
    boolean isClosed();
272
}
273

274
interface OutboundSseEvent extends SseEvent {
275
    String getName();
276
    String getId();
277
    String getComment();
278
    String getData();
279
    long getReconnectDelay();
280
    boolean isReconnectDelaySet();
281
    MediaType getMediaType();
282
}
283

284
interface SseBroadcaster extends AutoCloseable {
285
    CompletionStage<?> broadcast(OutboundSseEvent event);
286
    void register(SseEventSink sseEventSink);
287
}
288
```
289

290
[Server-Sent Events](./server-sent-events.md)