Whether or not a fully RESTful approach is used, the SRP HTTP Framework assumes the entire URL is meaningful. This is different from the RPC approach which fundamentally only cares about the command which appears before the “?” character and the query params which appear after the “?” character. Therefore, URLs are treated as paths which must begin at an entry point and then navigate to a final destination (end point). In fact, it is helpful to consider URLs as paths and the calling of an API as an attempt to map a path toward the end point destination.

To aid us in this understanding some terminology must be established. The following URL will be used for reference:

  • API URL – The API URL is the beginning portion of the URL that is minimally necessary to gain access to the API logic on the server. For instance, in the above example, https://www.myapplication.com/api is the API URL but https://www.myapplication.com is the domain and likely displays a home page (e.g., index.html). If the entire website is managed by API logic then these URLs would be one and the same.

  • Entry Point – Whether the API URL is submitted alone or with additional information (as pictured above), the request will begin with the entry point. This serves as a “front gate” and will determine if and how the next step in the URL path will be handled.

  • URL Segments – These are the parts of the URL which are separated by the “/” character. In the above URL, customers is a segment, 5678 is a segment, and phone is a segment. Starting with the entry point, the API navigates its way through each segment in a natural way. This is intended to assist the user with an intuitive understanding of the API. Thus, the URL above should hopefully be understood as “The Work Phone # that belongs to Customer #5678”.

  • End Point – This is a special URL segment that denotes the end of the URL itself. End points typically contain the name of a resource type (e.g., customers or invoices) or a specific resource identifier (e.g., 5676 or work). The end point is where the resolution of the request occurs.

In the SRP HTTP Framework module, the entry point, URL segments, and the end point are managed by separate HTTP services. Segments that are resource identifiers are handled by the preceding HTTP service. Thus, the service that is written to handle the customers segment will also look ahead to see if a specific customer (e.g., 5678) has been included. If so, it will process the request accordingly. A default entry point routine is HTTP_Entry_Point_Services, is included with SRP HTTP Framework. As a design standard, the name of the BASIC+ routine that acts as a web service for a given segment follows this pattern: HTTP_<URLSegment>_Services. Hence, the customers segment would be likely be managed by HTTP_Customers_Services.

Because customers is the first segment that follows the entry point, it would be the responsibility of HTTP_Entry_Point_Services  to pass the HTTP request onto HTTP_Customers_Services (and so on, as the URL path continues). The end point is where the HTTP response is generated. When the end point is a resource type, the service typically returns a collection (or list) of available resource identifiers (or Key IDs) that belong to the specific resource. If the end point is a specific resource identifier then the data corresponding to this resource is returned. In the above URL, phone is a resource type and work is the resource identifier.

If the journey through the URL path needs to be stopped prematurely, the current HTTP service can simply avoid calling the next service along the path and return an appropriate response. Here are just a few circumstances that could cause this to happen:

  • Credentials are unauthorized to access additional resources.

  • HTTP method is not supported for this URL.
     
  • Incorrect URL path provided. [In a true REST API this would only occur if the API itself generated an invalid URL. This can also happen if a user attempts to manually create the URL but does so incorrectly.]
  • No labels