RESTful Web Services Part 3 - URI

Uniform Resource Identifiers (URI)

    REST APIs use URIs to address resources.

• Good URI

            http://api.example.restapi.org/france/paris/louvre/leonardo-da-vinci/mona-lisa

• Bad URI

            http://api.example.restapi.org/68ddo-a9d3-11eo-9fic-0800200cga66

URI Formats

    The rules are in format of a URI. RFC 3986*

    URI syntax example

    URI = scheme "://" authority "/" path [ "?" query] ["#" fragment ]

URI Format Rules

• (/)  separator indicate a hierarchical relationship

            http://api.canvas.restapi.org/shapes/polygons/quadrilaterals/squares

• Tailing (/) should not be included in URIs

            http://api.canvas/restapi.org/shapes/

            http://api.canvas/restapi.org/shapes

• Hyphens (-) used to improve the readability URI

            //improve the readability of names in long path segments

            http://api.example.restapi.org/blogs/mark-masse/entries/this-is-my-first-post 

• Underscores (_) should not be used in URIs

            //(_) Partially obscured or completely hidden by this underlining.

            http://api.example_restapi.org/blog/mark-masse/this-is-my-first-post

• Lowercase letters should be preferred in URI paths

            //RFC 3986 defines URIs are case-sensitive to avoid unnecessary confusion, for instance

            http://api.example.restapi.org/my-folder/my-doc

            HTTP://API.EXAMPLE.RESTAPI.ORG/my-folder/my-doc

            http://api.example.restapi.org/My-Folder/my-doc

• File extensions should not be included in URIs

            http://api.college.restapi.org/students/3248234/transcripts/2005/fall

            http://api.college.restapi.org/students/3248234/transcripts/2005/fall.son

Resource Modeling

• ( /) separated path segment corresponding to unique resource

            http://api.soccer.restapi.org                                                -- Base Line

            http://api.soccer.restapi.org/leagues

            http://api.soccer.restapi.org/leagues/seattle

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

            http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet -- Bottom Line

Resource Archetypes

Resource archetypes helps consistently communicate the structures and behaviors.

• Document (Base Archetype)

            / /identifiers a document resource

            http://api.soccer.restapi.org/leagues/seattle

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

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

• Collection

            / /server-managed directory of resource

            http://api.soccer.restapi.org/leagues/seattle

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

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

• Store

            //client-managed resource repository

            PUT /users/1234/favorates/Alonso

• Controller

            //Executable functions, with parameters and return values; inputs and outputs; Controller names typically appear as the last segment in a URI path

            POST /alerts/245743/resend

URI Path Design

• A singular noun for document names

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

• A plural noun collection names

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

• A plural noun for store names

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

• A verb or verb phrase for controllers names

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

• Variable path segments substituted with identity-based Values

            http://api.soccer.restapi.org/leagues/{leaguesId}/teams/{teamId}/players/{playId}

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

• CRUD function names should not be used in URIs

            Preferred:DELETE /users/1234

            What not to do:GET /deleteUser?id=1234

            GET /deleteUser/1234

            DELETE /deleteUser/1234

            POST /users/1234/delete

• Define a query

            URI = scheme "://" authority "/" path [ "?" query][ "#" fragment ]

• Query is an unique identification of a resource

            http://api.college.restapi.org/students/morgan/send-sms

            http://api.college.restapi.org/students/morgan/send-sms?text=hello

• Query provide additional interaction capabilities
  • ad hoc searching
  • Filtering
• Query component used to filter collections or stores

            GET /users

            GET /user?role=admin

• Query component used to paginate collection or store results

            Parameters:pageSize (maximum number of contained elements)

            pageStartIndex (zero-based index of the first element)

            GET /user?pageSize=25&pageStartIndex=50