EAI REST API
Identification
Name: EAI REST API
Category: Technology
Version: v1.0
Modelling/Architecture Pattern: Modelling
Synonyms: No data
Contributor(s): Ed Walters
Attribution: Numerous articles available on the web, the most notable/accurate being https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design
Description
Context: The world wide web offers a host of resources which applications could make good use of, and which could be offered publicly in the form of web services. In a similar way, enterprises can create their own services to retrieve their or partner resources from a central location, to load their dynamic websites; for example the latest product data.
In the year 2000, Roy Fielding proposed Representational State Transfer (REST) as a universal architectural approach to designing web services. REST is an architectural style for building distributed systems based on accessing resources, which could be any form of document, data, images etc. During the course of retrieving a resource, remote functionality could be invoked in synchronous or asynchronous mode.
Problem: the architect needs to be able to represent the elements of a REST architecture, if that architecture is chosen or specified for certain integration requirements.
Trade-offs, Design Constraints (Forces):
The decision to use RESTful APIs requires us to consider the following forces:
• The resources desired must be accessible via an internet connection.
• The REST API is invoked in synchronous mode, which blocks the client. This brings into play forces like performance and the acceptability of delays, and the issue of scalability as the demand for a service fluctuates.
• The architect may have to think carefully about which operations to conduct on the client and which on the server in such an arrangement. Complex, lengthy operations on the server side are to be avoided where possible. REST is best used to recover resources that already exist.
• The server side may be layered in best practice, but this introduces the issues of latency and network reliability.
• There is some degree of coupling between client and server in this arrangement. It would be advisable to consider some form of broker between them, but this may not be practical in many cases, for performance reasons.
• Calls to REST APIs are inherently stateless, so the architect must consider the appropriateness of this for the application. If state needs to be tracked, this can be achieved by holding state on the client and including it in calls to the server.
• Finally, adequate security as always is an issue to resolve in any form of communication across the internet.
Solution Structure: The web service provider makes available a Universal Resource Identifier (URI) which identifies the resource. The location of the resource is called the Endpoint. The Endpoint is often expressed as a URL, given that HTTP is the usual protocol used across the web. The URL specifies a pathway to the resource available, starting from the server’s root folder. A Web Server is required to process requests coming in and send responses back. The Web Server may need to use other servers (e.g. a Resource Server) to access or derive the resource, or the resource could be available locally.
Solution Dynamics: The client invokes the web service by making a request for a resource, typically via HTTP, that is captured and processed by a web server. The request may contain authentication information and query parameters. The server processes the request to find the resource requested and performs any server-side processing. It then constructs a response, which is a suitable representation of the requested resource, and sends that back to the client. The API designer might include in the response further links to other related resources.
Layers/Aspects of the ArchiMate modelling language used: Application/Technology
Variants, Refinements and Combinations: This pattern may be seen as an alternative to EAI RPC, although RPC is usually about accessing remote functionality (uses verbs), whereas REST is usually about accessing resources (uses nouns).
Known Uses: This form of communication between client and web services is very frequent in web applications.
Other comments and references: No data
Pattern Metamodel
Example(s)
In this example an eCommerce website requests product data based on a category selection by the user.