Resources are a very fundamental concept in a RESTful web service. A resource represents an entity that is accessible via the URI that you provide. The URI, which refers to a resource (which is known as a RESTful web API), should have a logically meaningful name. Having meaningful names improves the intuitiveness of the APIs and, thereby, their usability. Some of the widely followed recommendations for naming resources are shown here:

• It is recommended to use nouns to name both resources and path segments that will appear in the resource URI. You should avoid using verbs for naming resources and resource path segments. Using nouns to name a resource improves the readability of the corresponding RESTful web API, particularly when you are planning to release the API over the internet for the general public.
• You should always use plural nouns to refer to a collection of resources. Make sure that you are not mixing up singular and plural nouns while forming the REST URIs. For instance, to get all departments, the resource URI must look like /departments.
• If you want to read a specific department from the collection, the URI becomes /departments/{id}. Following the convention, the URI for reading the details of the HR department identified by id=10 should look like /departments/10.
• The following table illustrates how you can map the HTTP methods (verbs) to the operations defined for the departments' resources:

• While naming resources, prefer more concrete names over generic names. For instance, to read all programmers' details of a software firm, it is preferable to have a resource URI of the form /programmers (which tells about the type of resource), over the much generic form /employees. This improves the intuitiveness of the APIs by clearly communicating the type of resources that it deals with.
• Keep the resource names that appear in the URI in lowercase to improve the readability of the resulting resource URI.
• Resource names may include hyphens; avoid using underscores and other punctuation.
• If the entity resource is represented in the JSON format, field names used in the resource must conform to the following guidelines:
  • Use meaningful names for the properties
  • Follow the camel case naming convention: The first letter of the name is in lowercase, for example, departmentName
  • The first character must be a letter, an underscore (_), or a dollar sign ($), and the subsequent characters can be letters, digits, underscores, and/or dollar signs
  • Avoid using the reserved JavaScript keywords
• If a resource is related to another resource(s), use a subresource to refer to the child resource. You can use the path parameter in the URI to connect a subresource to its base resource. For instance, the resource URI path to get all employees belonging to the HR department (with id=10) will look like /departments/10/employees. To get the details of employee with id=200 in the HR department, you can use the following URI: /departments/10/employees/200. To learn how to implement subresources using JAX-RS, refer back to the Understanding subresources and subresource locators in JAX-RS section in Chapter 4, Advanced Features in the JAX-RS APIs.