You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by ju...@apache.org on 2022/12/07 06:30:13 UTC
[apisix-website] branch master updated: docs: add new blog "How to choose the right API Style and Technology" (#1433)
This is an automated email from the ASF dual-hosted git repository.
juzhiyuan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix-website.git
The following commit(s) were added to refs/heads/master by this push:
new bf0443beab2 docs: add new blog "How to choose the right API Style and Technology" (#1433)
bf0443beab2 is described below
commit bf0443beab2a684f18cbd3320eeee08714ef9536
Author: Livermore <bo...@gmail.com>
AuthorDate: Wed Dec 7 08:30:08 2022 +0200
docs: add new blog "How to choose the right API Style and Technology" (#1433)
Co-authored-by: boburumurzokov <bo...@astrazeneca.com>
---
.../12/06/choose-the-right-api-style-technology.md | 140 +++++++++++++++++++++
1 file changed, 140 insertions(+)
diff --git a/blog/en/blog/2022/12/06/choose-the-right-api-style-technology.md b/blog/en/blog/2022/12/06/choose-the-right-api-style-technology.md
new file mode 100644
index 00000000000..0fdccb241c5
--- /dev/null
+++ b/blog/en/blog/2022/12/06/choose-the-right-api-style-technology.md
@@ -0,0 +1,140 @@
+---
+title: How to choose the right API Style and Technology
+authors:
+ - name: Bobur Umurzokov
+ title: Author
+ url: https://github.com/Boburmirzo
+ image_url: https://avatars.githubusercontent.com/u/14247607
+keywords:
+ - API Style
+ - Rest
+ - Event driven
+ - API Technologies
+ - API resources
+description: "How to decide on the right API style and which technology to choose for a style."
+tags: [Case Studies]
+image: https://static.apiseven.com/2022/12/06/638e30968ec3e.png
+---
+
+> In this post, we’ll go through **the 5 most popular API styles** and look at very common questions like “_How to decide on the right API style and which technology to choose for a style_” and provide practical scenarios where an [API Gateway](https://apisix.apache.org/docs/apisix/terminology/api-gateway/) can supplement their weaknesses.
+
+<!--truncate-->
+
+<head>
+ <link rel="canonical" href="https://iambobur.com/2022/12/06/how-to-choose-the-right-api-style-and-technology/" />
+</head>
+
+## No best API style
+
+[API](https://en.wikipedia.org/wiki/API)s are an essential design element in any software architecture that interconnects components digitally and allows various systems and devices to communicate easily with each other. When we built a new API, initially we think about the API design, and how the API interacts with the external world by using which **style and technology**.
+
+Note that there is no single best way of approaching all problems in a software design. The same is true with API styles. There is no “_best_” API style. They all have strengths and weaknesses that depend on the problem that is being addressed.
+
+Let’s go through each style and understand the main properties, interaction model, and limitations.
+
+1. Resource.
+2. Hypermedia.
+3. Query.
+4. Tunnel.
+5. Event-Based.
+
+Then we pick a suitable style and technology that works well for the given style.
+
+## Resource style
+
+The **resource style** as the name implies is _resource-oriented_. Many of today’s APIs use the resource style, and this can be easily verified by the popularity of [OpenAPI](https://www.openapis.org/), which is the most popular way of describing resource-oriented APIs. In this style, the main focus is on which resources to expose to consumers so that they can interact with these resources.
+
+
+
+The resource in this context can be assumed to be similar in scope to what you would have in resources such as web pages when designing a website. The idea of resources gives us a great way to expose the relevant aspects of an API’s functionality and at the same time allows us to hide implementation details behind the resources. There can be resources for persistent concepts such as products, product categories, and customer information. Also, there can be resources for process-oriented [...]
+
+For the resource style, there is [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) as an architectural pattern, but that doesn’t mean that REST gives you concrete technologies. For REST, choosing [HTTP](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol) as a protocol is a preferred choice, and for the representation format, it’s probably safe to say that [JSON](https://www.json.org/json-en.html) by far overshadows any other representation (such as the [XML](ht [...]
+
+In developing REST APIs with many collections of resources that are integrated with backend HTTP endpoints, you can use [API Gateway features](https://apisix.apache.org/docs/apisix/getting-started/) to help you with all aspects of the API lifecycle, from creation to monitoring your production APIs. API Gateway REST APIs use a request/response model where a client sends a request to a service and the service responds back synchronously. You can read more about [how to choose the right API [...]
+
+Resource style lacks is the ability to better represent workflows across these resources. The **hypermedia style** adds a key component to the resource style to address resource-linking concerns.
+
+## Hypermedia Style
+
+Just as on the web, the most important paths across resources can be navigated by simply _using links_ between them (instead of having to know each resource individually and enter its URI in the browser’s address bar); the [hypermedia style](https://www.infoq.com/articles/hypermedia-api-tutorial-part-one/) does the same but for the resources of an API.
+
+
+
+On the web, humans read pages and then decide which link to follow. For hypermedia APIs, this decision is usually made by a machine. This means that links need to have machine-readable labels so that machines can identify the available options and then make a choice. These labels are conceptually similar to the text of a link that humans click on web pages, but the labels are represented in the machine-readable representation of resources, which nowadays in many cases will be JSON. In a [...]
+
+> _HATEOAS_ is an abbreviation for Hypermedia As The Engine Of Application State. HATEOAS is the aspect of REST, which allows for dynamic resource routing.
+
+There are two main advantages of **hypermedia APIs over resource-style APIs**:
+
+- They provide all the links necessary in the previous response to choose the available resources in the next step.
+- Links span resources, and it doesn’t matter whether these resources are provided by one API or several APIs.
+
+All of this sounds very positive because the Hypermedia style provides the necessary knowledge for API consumers to discover your API themselves and what resources you offer to them. You can build a hypermedia-driven REST service with any programming language and framework used in your stack. For example, using [ASP.NET Web API](https://learn.microsoft.com/en-us/archive/msdn-magazine/2013/january/asp-net-building-hypermedia-web-apis-with-asp-net-web-api) or [Spring Boot Rest API](https:/ [...]
+
+However, the ease of browsing may increase the risk of the learner skipping through the materials and getting fragmented information. Also, since data is shared between client and server, it can also lead to “_chatty_” APIs that require a number of interactions for the client to access all required information, and what if API endpoints are exposed by multiple backend services (microservices and serverless APIs)?. The latter challenge can be solved by leveraging an API Gateway with _a re [...]
+
+Moreover, API consumers do not know what they want from the very beginning and it is more efficient to write a query to get exactly what they want as is offered by the **query style** in the next section.
+
+## Query Style
+
+The _query style_ is rather different from the resource and hypermedia styles because it provides _a single entry point_ to access a potentially large set of resources. The idea of the query style is that these resources are managed in a structured form by the API provider. This structure can be queried, and the response contains the query results. At some level, this can be seen as similar to how databases work. They have an underlying data model for the data they store, and a query lan [...]
+
+
+
+One benefit of the query style is that each consumer can request exactly what they want. This means that with a well-constructed query, it may be possible to combine results that would have required numerous requests in resource/hypermedia APIs. For example, instead of sending several HTTP requests to different endpoints, you can `POST` a single “_query_” for all you need.
+
+For the query style, it’s probably fair to say that [GraphQL](https://graphql.org/) by now is by far the most popular choice when it comes to building [single-page applications](https://en.wikipedia.org/wiki/Single-page_application) (SPAs). It is a language for querying databases from client-side applications. The big advantage that GraphQL has is that it plugs into a JSON-based ecosystem. While GraphQL does not use JSON for queries, it returns results in JSON which make it easy to proce [...]
+
+Although query style has negligible disadvantages over its advantages, we can identify one of them is the query complexity. API consumers need to have a good understanding of the underlying data and query models (so that they know how to use the query API properly and make efficient requests to avoid recursion or getting too many nested resources). Also, it is more complicated to implement a simplified cache with GraphQL than implement it in resource style because REST APIs have multiple [...]
+
+Nevertheless, the last two mentioned downsides (caching and rate-limiting) can be developed by introducing the API Gateway between the client and data store to win in this situation. For example, an open-source [Apache APISIX](https://apisix.apache.org/) API Gateway has the matching ability to recognize GraphQL syntax. By efficiently matching GraphQL statements carried in requests, it can filter out abnormal traffic to further apply [rate-limiting policies](https://apisix.apache.org/doc [...]
+
+## Tunnel Style
+
+In _tunnel style_, an API is a collection of functions that can be invoked remotely. APIs become a simple extension of what is in a local programming scenario where all exposed procedures are available as APIs. The tunnel style is convenient for developers because it can take very little effort to create APIs.
+
+
+
+A common technique used in this style is the [Remote Procedure Call](https://en.wikipedia.org/wiki/Remote_procedure_call) method. RPC is a request-response protocol, where a client sends a request to a remote server to execute a specific procedure, and then the client receives a response back. However, RPC APIs are much more difficult to maintain and update than REST APIs, so again RPC APIs aren’t used as much in modern API development.
+
+[gRPC](https://grpc.io/) is an efficient tunnel-style (RPC) implementation and is well-suited for distributed systems. It has SDKs for many languages and platforms, so it can be used widely, for communication across platforms and languages. gRPC is super fast and efficient because it uses [Protocol Buffers](https://en.wikipedia.org/wiki/Protocol_Buffers) (protobufs) to serialize and deserialize, the HTTP/2 standard for optimized binary transfers, and bidirectional streaming to avoid (lo [...]
+
+Tools can be used to expose procedures as APIs, in which case a lot of the task of “creating the API” can be automated. There still should be some management layer for securing the APIs, but that can be addressed by using a component such as an API gateway and its [gRPC proxying](https://apisix.apache.org/blog/2021/12/30/apisix-proxy-grpc-service/) ability to convert payloads from one format to another over the same transport (from REST to gRPC or vice versa) if different API protocols a [...]
+
+## Event-Based Style
+
+In the _event-based style_, the API provider creates events that are then delivered to consumers of the API instead of consumers requesting something from the provider. Consuming applications expect to be informed of any change of state on a specific record or records on API. There are many ways and technology options to consider when implementing an event-driven API. For example, we explored [how to build Event-Driven APIs with Webhook and API Gateway](https://apisix.apache.org/blog/202 [...]
+
+
+
+Another approach is that event consumers connect to a _message broker_ that decouples them from event producers. The message broker takes care of managing events, and consumers must subscribe to certain event types so that the broker can make sure that events of this type are delivered to subscribers. In this case, the architecture is much more centered around the delivery broker, and all event producers and consumers are connected to this message broker. In this case, a good technology [...]
+
+Some drawbacks of choosing an event-based style are, it takes more time to implement compared to other styles, it may trigger multiple duplicate messages across different services if the style is not properly applied, error handling and troubleshooting can be challenging without installing & configuring third-party tools to monitor the event flow effectively. However, you can put the API Gateway in front of even-driven APIs when [observing modern applications](https://dev.to/apisix/apis- [...]
+
+## Wrapping Up
+
+As we reviewed, 5 styles were the foundation of popular approaches and technologies such as [REST](https://en.wikipedia.org/wiki/Representational_state_transfer), [OpenAPI](https://www.openapis.org/), [HTTP](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol), [gRPC](https://grpc.io/), [GraphQL](https://graphql.org/), and [Kafka](https://kafka.apache.org/). The most important lesson to learn about these **5 API styles** is that there is no “best style”. When it comes to choosing [...]
+
+**Problem** - As discussed in the individual styles, each style has a certain focus and certain strengths. Thus, it is important to think about the problem that is addressed with an API.
+
+**Consumer** - Every API is built for consumption, and thus an API’s consumers always should be an important design aspect. Since APIs ideally are reused, it’s not always possible to plan for all consumers and their constraints, but it makes sense to design with at least some consumers in mind and to make assumptions about others.
+
+**Context** - Most APIs are part of an API landscape. That landscape can have a different audience and scope, depending on whether the API is meant for internal, partner, or public use.
+
+Ultimately, the style that you and your team are more familiar with and easier to build might be a good fit for your project. Sometimes, we need to use different styles together in one software project.
+
+### Related resources
+
+- [API fundamentals](https://developer.ibm.com/articles/api-fundamentals/).
+
+- [API Styles: SOAP, REST, RPC, GraphQL and more](https://api-university.com/blog/styles-for-apis-soap-rest-and-rpc/).
+
+### Recommended content
+
+- [How to build Event-Driven APIs with Webhook and API Gateway](https://apisix.apache.org/blog/2022/11/07/webhook-api-gateway-event-driven-apis/)
+
+- [10 most common use cases of an API Gateway](https://apisix.apache.org/blog/2022/10/27/ten-use-cases-api-gateway/).
+
+- [How to choose the right API Gateway](https://iambobur.com/2022/11/22/how-to-choose-the-right-api-gateway/).
+
+- [A poor man's API](https://apisix.apache.org/blog/2022/11/23/poor-man-api/).