Designing REST Web services

Planning the resources that the client can interact with is essential to REST Web service design.

Each component in a RESTful Web service is a resource that can be accessed using standard HTTP methods. The starting point in identifying resources is to analyze your business domain and extract the nouns (and most appropriately pluralized nouns) that are relevant to your business needs. For example, “customers” and “accounts” are resources in a typical business domain.

Once the nouns (resources) have been identified, then the interactions with REST web services can be modeled as HTTP verbs against these nouns. REST relies on this resource/HTTP method combination.

For example, imagine you have a Web service like the "StockQuote" service mentioned in the Introduction to Web services. In this simplification of the business domain, we can begin to identify some types of resources:
  • quotes
    • /id
    • /price
    • /category
    • etc.
  • companies
    • /id
    • /name
    • /rating
    • etc.
  • users
    • /id
    • /name
    • etc.
Here's how you might begin to build resource identifiers. For example, "users" is a collection resource and "user" is a single resource in this domain. You can identify "users" using the URI with path "/users" to locate the resource. You can identify a single user resource using the path "/users/{id}". The path or endpoint is a logical not a physical URL that determines the resource you are requesting.
Note: You may find it helpful also to think of the resource in terms of CRUD, where each resource supports the action of Create, Read, Update, and Delete using the HTTP verbs PUT, GET, POST, DELETE.
For instance, the following may now represent endpoints to the StockQuote service for the users entity. 
Users

GET http://localhost:8090/StockQuote/users       - Return a list of all users (requires authentication)
GET http://localhost:8090/StockQuote/users/id    - Return the user with that id 
POST http://localhost:8090/StockQuote/users      - Create a new user. Return a 201 status code and the newly created id 
PUT  http://localhost:8090/StockQuote/users/id   - Update the user with that id
DELETE http://localhost:8090/StockQuote/users/id - Delete the user with that id

Functions in the REST Web service now need to be created to respond to requests for services based on those endpoints. For this it is recommended to always use the GWS REST high-level framework in your Web service. Functions require considerably less code in your application and are easier to use in comparison with low-level APIs.