Designing and Implementing Hypermedia APIs

The topic of this article (the second article in this series) is the implementation of the Hypermedia server. The message design and problem domain descriptions used in this article have been described in previous articles. In this article, we'll start with a brief overview of the role of the hypermedia server (routing, Evaluation, and execution), and then discuss its underlying implementation, including the component layer, the presentation layer, and the connection layer. Finally, we will briefly describe the client browser for a Hypermedia API, especially the limitations of common web browsers and command-line tools, and the benefits of the media type browser.

This article details the high-level details required to build a fully functional server using Node.js. To make things relatively simple, the example implementation in this article does not use other custom node modules or frameworks, and even the storage processing of simple disk files is not used. Because the implementation of this article is only skeleton and basic implementation, it does not have all the features and security of a real product-level server, but you can still learn the main technical points of implementation. Also, while this server is built using Node.js, it's no problem to translate the ideas presented in this article into other programming languages, frameworks, and/or platforms that you like.

Attention:

All source code for this server implementation can be obtained from the GitHub.

Hyper Media API Server

The Hypermedia API server adds a lot of functionality based on the basic Web server. Like common Web servers, hypermedia API servers receive requests, process requests, and return responses. However, the Hypermedia API server does some other work. They are like translators, sending each request in a predefined message format, it translates into content that can be understood by the server components (storage, database, and business logic) and then translates back into the predefined format, which may contain the information required by the client sending the request to do the next action. The typical RPC-type API server does not contain this information.

This additional information may include whether the client is able to see the relevant resources, whether it can perform a search operation, and whether it can modify the data stored on the server. All of this is based on the media type design that the requesting client understands, by increasing hypermedia control (link and form) communication. A client request may be bound to a user's identity, and that identity may (or may not) contain some additional privileges, and also affect what is valid when the next request is made. The corrections made to the response are context-driven, which is one of the key value-added elements added to the implementation of the Hypermedia type.

Routing

In a Web environment, the first task of an API server is to receive, parse, and route incoming requests. When designing a Web API server, the URI is typically routed to the server's request as a preferred method. This process is done by first parsing the URI into content such as a path fragment and a query string, and then using that information to send the requested details (including the possible request body data) to the correct internal component for processing.

For example, the following HTTP request:

Get/users/?search=pending
host:http://www.example.org
Accept:application/vnd.collection+json
authorization:q1w2e3r4t5=

The first part of this request tells the server that a client wants to perform a "read" operation that searches for a suspended user on the www.example.org server. The second part of the client request indicates that the response data should be in Collection+json format (a registered hypermedia type). The last part of the request indicates that the request was issued by an authorized user and can be authenticated by the encrypted value in the authorization header.

The server usually decomposes the URI into different parts:

Users

Search=pending

A valid request is then generated and sent to the corresponding internal component for processing:

Results = Users.search

(' pending ');

The processing result is converted to the requested format and sent back to the client:

http. Response = 

Representation (results, ' collection+json ');

The above example uses pseudo code, but you can learn the basics. The API server receives, routes, and processes the request, and then creates a conforming result to return to the client.