More than anything else, the SRP HTTP Framework is designed to enable OpenInsight developers to build web APIs. This means it is designed with the OpenInsight developer in mind. It attempts to bring out the best of the OpenInsight development environment. We would suggest that this matches the goals of the original OECGI (OICGI once upon a time) and traditional INET routines. However, whether using INET or the RESTful architecture that the SRP HTTP Framework provides, some fundamental knowledge of HTTP is necessary. Our toolkit attempts to encourage proper use of the HTTP protocol. Therefore, our documentation will rely heavily upon HTTP communication terminology. If you are unfamiliar with this, we encourage you to go through the following basic primer on HTTP.
HTTP communications is analogous to making a function call. Consider these similarities:
- Functions are executed from a calling operation, typically another routine or an event handler. Likewise, HTTP communications are initiated from a calling operation, typically a request from a web browser or other HTTP-aware client. HTTP Requests are well-defined operations which will be touched upon throughout this document.
- The caller (or client) waits until the function (or server handling the HTTP request) is finished. While other factors may interrupt the wait (such a timeout or critical disconnection), the normal expectation is a response of some kind.
- Functions return the results of a request back to the caller, typically through a return variable. Some programming environments might also allow arguments to be modified or global variables to be updated. Likewise, HTTP communications also return the results of a request back to the caller. This is referred to as the HTTP Response, another well-defined operation. HTTP Responses can either be handled by a server-side program or through the retrieval of a local file.
With that high-level comparison in mind, let’s examine the anatomy of the two basic HTTP means of communication: Requests and Responses:
Finally, successful APIs know how to accommodate or negotiate specific requests using the HTTP headers:
