- What Is REST?
- The Pieces of a RESTFul Web Service
- Introducing JAX-RS
- More JAX-RS Annotations
- JAXB and More Interesting XML-Based Web Services
- JSON Serialization
- More on Content Negotiation
- RESTful SOA
- Summary
This chapter is from the book
This chapter is from the book
This chapter is from the book
The Pieces of a RESTFul Web Service
Creating a RESTful web service is like forming a sentence: You need a noun, a verb, and an adjective. In REST terms, nouns are the resources URLs point to. The verbs are the HTTP actions on resources. The adjectives (okay, this might be stretching the analogy) are the formats of data in which the resources are represented. We like to lay this out in tables similar to the way we broke down sentences in primary school. For example, Table 4.1 outlines how you might describe a set of services related to a prospect list application, such as the one in Chapter 2, “WAS and the Liberty Profile.”
Table 4.1 Prospect URI Structure
|
Sentence (Resource Description) |
Noun (URI) |
Verb (Action) |
Adjectives (Formats) |
|
List all the prospects. |
.../prospects |
GET |
JSON, XML |
|
Get a specific prospect. |
.../prospects/{id} |
GET |
JSON, XML |
|
Add a contact. |
.../prospects |
POST |
JSON, XML |
|
Delete a specific contact. |
.../prospects/{id} |
DELETE |
JSON, XML |
- Nouns/URIs: URLs are the most identifiable part of the web and, as such, are a straightforward way of organizing your services. Organizing a unique URI for each resource avoids confusion and promotes scalability.
- Verbs/actions: In REST, you usually perform four HTTP operations against these URLs: POST, GET, PUT, and DELETE. (HTTP supports a few more actions, or officially request-methods, but these are the interesting ones.) Although having just four operations might seem constraining, the simplicity is somewhat liberating. These operations roughly map to Create, Read, Update, and Delete (CRUD). CRUD provides the foundational functions needed to interface with a relational database or other data store, so you can use these four methods in interesting and powerful ways.
- Adjectives/data formats: There are well known data types (the MIME types—text/html, image/jpeg) that HTTP servers and browsers natively support. Simple XML and JSON allow more custom data formats that are self-describing and can easily be parsed by the user. (When we say parse, we also mean “read with your eyes and parse with your brain.”)
Using REST enables you to take advantage of many assumptions made by web infrastructure. Because you constrain the problem to only HTTP, you can make assumptions about items such as caching and HTTP-based security models. Because these technologies are ubiquitous, following this approach enables you to take advantage of existing solutions such as browser caches and web security proxies. By making your resources stateless, you can easily partition your resources across multiple servers, providing scalability opportunities. Another advantage is you can easily test HTTP-based services using a browser or a simple command-line tool such as cURL. By following RESTful idioms such as representing connections between resources by links in the data, you can enable runtime discovery of additional services. Finally, from the consumer perspective, services written to RESTful idioms have a regularity that enables you to benefit from examples and to practice reuse through cut-and-paste.
Building an effective REST architecture involves many aspects:
- Resources
- Resource types
- Query formats, headers, and status codes
- Content negotiation
- Linking
- Versioning
- Security
- Documentation
- Unit tests
We begin to cover these issues in this chapter, and we address more of these topics more fully in later chapters.