REST requires each resource to have at least one URI. A RESTful service uses a directory hierarchy like human readable URIs to address its resources. The job of a URI is to identify a resource or a collection of resources. The actual operation is determined by an HTTP verb. The URI should not say anything about the operation or action. This enables us to call the same URI with different HTTP verbs to perform different operations.
Suppose we have a database of persons and we wish to expose it to the outer world through a service. A resource person can be addressed like this:
This URL has following format: Protocol://ServiceName/ResourceType/ResourceID
Here are some important recommendations for well-structured URIs:
Use plural nouns for naming your resources.
Avoid using spaces as they create confusion. Use an _ (underscore) or – (hyphen) instead.
A URI is case insensitive. I use camel case in my URIs for better clarity. You can use all lower-case URIs.
You can have your own conventions, but stay consistent throughout the service. Make sure your clients are aware of this convention. It becomes easier for your clients to construct the URIs programmatically if they are aware of the resource hierarchy and the URI convention you follow.
A cool URI never changes; so give some thought before deciding on the URIs for your service. If you need to change the location of a resource, do not discard the old URI. If a request comes for the old URI, use status code 300 and redirect the client to the new location.
Avoid verbs for your resource names until your resource is actually an operation or a process. Verbs are more suitable for the names of operations. For example, a RESTful service should not have the URIs http://MyService/FetcthPerson/1 or http://MyService/DeletePerson?id=1.
Query Parameters in URI
The preceding URI is constructed with the help of a query parameter:
The query parameter approach works just fine and REST does not stop you from using query parameters. However, this approach has a few disadvantages.
Increased complexity and reduced readability, which will increase if you have more parameters
Search-engine crawlers and indexers like Google ignore URIs with query parameters. If you are developing for the Web, this would be a great disadvantage as a portion of your Web service will be hidden from the search engines.
The basic purpose of query parameters is to provide parameters to an operation that needs the data items. For example, if you want the format of the presentation to be decided by the client. You can achieve that through a parameter like this:
Including the parameters format and encoding here in the main URI in a parent-child hierarchy will not be logically correct as they have no such relation:
Query parameters also allow optional parameters. This is not otherwise possible in a URI. You should use query parameters only for the use they are intended for: providing parameter values to a process.
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.