URI Query Design

A query string is the part of a uniform resource locator (URL) containing data that does not fit conveniently into a hierarchical path structure. The query string commonly includes fields added to a base URI by a Web browser or other client application, for example as part of an HTML form.

Following are the rules relating to the design of URI queries.

• Rule: The query component of a URI may be used to filter collections or stores

GET /users

GET /users?role=admin

• Rule: The query component of a URI should be used to paginate collection or store results

GET /users?pageSize=25&pageStartIndex=50

POST /users/search

Parameters: pageSize, pageStartIndex

URI Path Design

Each URI path segment, separated by forward slashes (/), represents a design opportunity. Assigning meaningful values to each path segment helps to clearly communicate the hierarchical structure of a REST API’s resource model design.

• Rule: A singular noun should be used for document names

http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players/claudio

• Rule: A plural noun should be used for collection names

http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players00

• Rule: A plural noun should be used for store names

http://api.music.restapi.org/artists/mikemassedotcom/playlists

• Rule: A verb or verb phrase should be used for controller names

http://api.college.restapi.org/students/morgan/register

http://api.example.restapi.org/lists/4324/dedupe

• Rule: Variable path segments may be substituted with identity-based values. The URI template example below has three variables (leagueId,teamId, and playerId):

http://api.soccer.restapi.org/leagues/{leagueId}/teams/{teamId}/players/{playerId}

URI Design Rules for RESTful APIs

REST APIs use Uniform Resource Identifiers to address resources. It tells you how a site is organized. Best practices insist that the following rules have to be followed in order to maintain a common standard while designing URIs for APIs using REST architecture.

• Rule: Forward slash separator (/) must be used to indicate a hierarchical relationship.The forward slash (/) character is used in the path portion of the URI to indicate a hierarchical relationship between resources.
  • http://api.canvas.restapi.org/shapes/polygons/quadrilaterals/squares
• Rule: A trailing forward slash (/) should not be included in URIs. A REST API must generate and communicate clean URIs and should be intolerant of any client’s attempts to identify a resource imprecisely. REST APIs should not expect a trailing slash and should not include them in the links that they provide to clients.
• Rule: Hyphens (-) should be used to improve the readability of URIs To make your URIs easy for people to scan and interpret,
• Rule: Underscores (_) should not be used in URIs. Text viewer applications (browsers, editors, etc.) often underline URIs to provide a visual cue that they are clickable.
• Rule: Lowercase letters should be preferred in URI paths. When convenient, lowercase letters are preferred in URI paths since capital letters can sometimes cause problems — URIs are case sensitive.
• Rule: File extensions should not be included in URIs. The best practice is to use headers in the HTTP request, which we will see about later on, to define the file types that are used

Below are the naming conventions to be used while designing the authority portion of a REST API.

• Rule: Consistent subdomain names should be used for your APIs. The top-level domain and first subdomain names (e.g., soccer.restapi.org) of an API should identify its service owner
• Rule: Consistent subdomain names should be used for your client developer portal. Many REST APIs have an associated website, known as a developer portal, to help onboard new clients with documentation, forums, and self-service provisioning of secure API access keys. If an API provides a developer portal, by convention it should have a subdomain labeled developer.

📷 Toa Heftiba