RESTapi URL Naming Conventions

Topics to be covered in this article –

  1. Basic URL naming conventions.
  2. Conventions for an API using a specific resource by using its ID.

We have already discussed the HTTP verbs and their usage in this post.

Basic URL Naming Conventions

Well, this looks easy, anyone can name/design the URL anyway he wishes. But it is more tough than it looks and hell important coz this is what makes your platform/service incline towards REST standards. Good naming convention is a MUST practise when building API’s. The basic convention is like –

/resource/{resource_id}/resource/resource_id

The sequence of order is from parent to its child – /parent/child/grandchild

For example, these are some good URL examples

  • /blog – Working of Blogs as a whole.
  • /blog/{blog_id} – Working on a particular blog having ID as blog_id.
  • /blog/{blog_id}/article – Working on articles belonging to blog with ID as blog_id.
  • /blog/{blog_id}/article/{article_id} – Working on an article with ID as article_id inside blog with ID as blog_id

Also, note that these two types of URL have different meanings as how you design your system.

  1. /blog/{blog_id}/article – This type of URL’s are used when you mean that articles are related as children of a blog.
  2. /article – This type of URL’s are used when you mean that article is an independent entity and may or may not be related to any blog.

Conventions for an API using a specific resource by using its ID

Many of you must be thinking when we can pass the ID as a Query parameter, why are we embedding it inside the URL itself. Well, let’s dive deep inside.

There are three types to send information to an API –

  1. URL parameters.
  2. Query Parameters.
  3. Body of request.

URL Parameters

These are the values we embed inside the URL itself like – /blog/{blog_id}. This is done as each resource should be accessed/handled by its own URI (unique resource identifier). This means that if there are 2 blogs, each one would have their own physical address inside the system (URI) so as to uniquely identify them.

Query Parameters

These are those values which you send at the end of your URL like – /blog?name=Shrey&surname=Batra. Over here, the variables “name” and “surname” are sent as query parameters in the URL and act as extra information needed to process a resource “blog”. These values may or may not be used as unique identification for the resource, but are used for querying or limiting the data/resources in that API.

Body

This is a type of method used in each type of request except GET. This information is encrypted and then sent over the network and are not visible in the API url being called in plain text format. They are mostly used to send excess information and a variety of information as they have a larger character space than the URL’s. They also support new lines, long lines of text, etc much more easily than the URL as the body is generally a JSON object. All the properties of JSON can be used with this.

Even passwords, when sent for authentication, are sent via the body so that it is not visible as plain text of URL.

If you have more doubts or need explanation, do comment below. Also Share, Like and follow the blog to keep up with updates.!!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Powered by WordPress.com.

Up ↑

%d bloggers like this: