農場js

by Kevin Kononenko

凱文·科諾年科(Kevin Kononenko)

通過銷售農場商品來解釋Web API (Web APIs explained by selling goods from your farm)

If you have been to a farmer’s market or farm stand, then you can understand the concept of an application programming interface (API).

如果您去過農民的市場或農場攤位，那么您可以了解應用程序編程接口(API)的概念。

If you are new to web development, you probably hear the term “API” a lot.

如果您不熟悉Web開發，則可能會經常聽到“ API”一詞。

“I can’t wait until that company releases their public API!”

“我等不及該公司發布其公共API！”

“That company’s API is a confusing mess.”

“該公司的API令人一團糟。”

“Do they have an endpoint for that data in their API?”

“他們的API中是否有該數據的端點？”

Understanding the concept of an application programming interface (API) can be pretty difficult if you are not familiar with concepts like SOAP, HTTP, and XML.

如果您不熟悉SOAP，HTTP和XML等概念，那么理解應用程序編程接口(API)的概念可能會非常困難。

So, I wanted to find a way to explain the way that web APIs work as a whole, so that when you get into the nitty-gritty technical details, you will understand how it all fits together.

因此，我想找到一種方法來解釋Web API作為一個整體的工作方式，以便當您深入了解具體的技術細節時，您將了解它們如何結合在一起。

In this tutorial, you are the owner of a farm that sells five products: chicken, pork, eggs, tomatoes, and corn.

在本教程中，您是一個農場的所有者，該農場出售五種產品：雞肉，豬肉，雞蛋，西紅柿和玉米。

In order to understand this tutorial, you just need to understand the difference between server-side code (back-end) and client-side code (front-end). You can read the beginning of my guide to GET/POST if you are not already familiar with server vs. client.

為了理解本教程，您只需要了解服務器端代碼(后端)和客戶端代碼(前端)之間的區別。如果您還不熟悉服務器與客戶端，則可以閱讀GET / POST指南的開頭。

GUI和API之間的區別 (The Difference Between A GUI and an API)

Let’s start with a familiar way to use the web. The web browser, like Chrome, is an example of a graphical user interface (GUI). As the user, you can interact with a user-friendly tool in order to accomplish tasks, like booking flights or searching Google.

讓我們從熟悉的網絡使用方式開始。像Chrome這樣的網絡瀏覽器是圖形用戶界面(GUI)的示例。作為用戶，您可以與用戶友好的工具進行交互，以完成任務，例如預訂航班或搜索Google。

The GUI allows website visitors to interact with code on the server in a controlled and structured fashion.

GUI允許網站訪問者以受控和結構化的方式與服務器上的代碼進行交互。

As a farm owner, this is kind of like the farm stand that you set up on your property or your stall at the farmer’s market.

作為農場主，這有點像您在物業上設置的農場攤位或在農夫市場上的攤位。

You can’t just stack your goods inside your barn, allow visitors to come in, and then expect to make money. Instead, you need to set up a booth so visitors can quickly understand your available goods and pricing.

您不能只是將貨物堆放在谷倉內，讓訪客進來，然后期望賺錢。相反，您需要設置一個攤位，以便訪客可以快速了解您的可用商品和價格。

This is the way that customers “interact” with your hard work. They don’t need to understand the planting process, or the equipment you use, or the processing. They just see the final product.

這是客戶與您的辛勤工作“互動”的方式。他們不需要了解種植過程，您使用的設備或加工過程。他們只是看到最終產品。

Notice how every customer experiences a one-to-one interaction. When they arrive at your stall, they are only looking at products from your farm.

注意每個客戶如何體驗一對一的互動。當他們到達您的攤位時，他們只是在看您農場的產品。

那么什么是API？ (Then What Is An API?)

There are other ways to sell your products besides direct to consumer. You can also sell to distributors and local restaurants, so that your products can be included in different dishes or sold in a grocery store.

除了直接銷售給消費者外，還有其他銷售產品的方法。您還可以出售給分銷商和當地餐館，這樣您的產品可以包含在不同的菜肴中，也可以在雜貨店出售。

This is a new way for consumers to “experience” your product. Sure, they might not know whose eggs are in their omelette when they order breakfast at the local diner, but they are still “using” your product.

這是消費者“體驗”您的產品的新途徑。當然，他們在當地的餐館點早餐時可能不知道誰的雞蛋在煎蛋中，但他們仍在“使用”您的產品。

But, from your perspective as a farm owner, you have a completely different sales process and supply chain. Now, you don’t need to carefully arrange a booth for consumers. Instead, you probably need to add a shipping bay to your barn so that distributors and restaurants can pull up their trucks and load up. You also need to package your goods for larger sales.

但是，從您作為農場主的角度來看，您擁有完全不同的銷售流程和供應鏈。現在，您無需為消費者精心安排攤位。取而代之的是，您可能需要在谷倉中增加一個運輸區，以便分銷商和飯店可以拉起卡車來裝貨。您還需要包裝商品以提高銷量。

This is similar to the concept of an API. When you build an API, you make it possible for other developers to access your data and use it in their applications.

這類似于API的概念。構建API時，其他開發人員可以訪問您的數據并在其應用程序中使用它們。

Just like restaurant customers can “experience” your chickens’ eggs by eating an omelette, website users can “experience” your product on somebody else’s website through a widget on the website or code on the other company’s servers.

就像餐廳客戶可以通過吃煎蛋來“體驗”雞的蛋一樣，網站用戶也可以通過網站上的小部件或另一家公司的服務器上的代碼在別人的網站上“體驗”您的產品。

Now, we have a new level of interaction. Your distributors and restaurant customers might interact with you one-on-one by visiting the farm, but they then expose thousands of customers to your products when they sell them later.

現在，我們有了新的互動水平。您的分銷商和餐廳客戶可能會通過訪問農場與您進行一對一的互動，但是當他們以后出售產品時，他們就會使成千上萬的客戶接觸到您的產品。

As the farm owner, you still must set up processes so that you can successfully serve these distributors. Similarly, an API is a structured way that others can utilize your server-side code. As the developer, you still have full control.

作為服務器場所有者，您仍然必須設置流程，以便可以成功為這些分發服務器提供服務。同樣，API是其他人可以利用您的服務器端代碼的一種結構化方式。作為開發人員，您仍然擁有完全控制權。

I used a search widget as an example in the image above, but really, just about anything could be used to access an API. That is just one example of a common way that website users experience APIs from 3rd parties. Other common ones include:

我在上圖中以搜索小部件為例，但實際上，幾乎任何東西都可以用來訪問API。這只是網站用戶體驗來自第三方的API的一種常見方式的示例。其他常見的包括：

Mapping tools
貼圖工具
Payment processing
交付過程
Weather data
天氣資料

通過API可以訪問什么？ (What Can Be Accessed Through An API?)

Let’s say that you want to start selling eggs from your farm to distributors and restaurants. You would need to set up a series of processes on your farm to support this:

假設您要開始從農場向分銷商和飯店銷售雞蛋。您需要在服務器場上設置一系列過程來支持此操作：

Mass storage of eggs
大量儲存雞蛋
Accounting for monthly billing to customers
每月向客戶計費
A shipping area to load up eggs onto trucks.
一個將雞蛋裝載到卡車上的運輸區域。

Before you set up all these processes, you need to decide whether you are ready to accept mass orders of eggs in the first place. Do you have enough hens to produce the right number of eggs on a weekly basis? If you don’t, you may put too much strain on your system and disappoint your customers when you run out of eggs.

在設置所有這些過程之前，您需要首先確定是否準備好接受大量的雞蛋訂單。您是否有足夠的母雞每周生產適當數量的雞蛋？如果不這樣做，可能會給系統造成太大的壓力，并在雞蛋用完時使客戶失望。

API developers set up endpoints that allow other developers to access specific data from their database. The example above would be an “eggs” endpoint. If you do not create one in the first place, then customers cannot buy eggs from you.

API開發人員設置了端點，允許其他開發人員從其數據庫訪問特定數據。上面的示例將是一個“雞蛋”端點。如果您不首先創建一個雞蛋，那么客戶將無法從您那里購買雞蛋。

You can set up specific endpoints for each product from your farm- chickens, pork, eggs, tomatoes and corn. Some may only be accessible through the farmer’s market (GUI) because you are not sure if you are ready to ramp up production to meet the needs of distributors.

您可以為農場，雞肉，豬肉，雞蛋，西紅柿和玉米中的每種產品設置特定的終點。有些產品可能只能通過農貿市場(GUI)訪問，因為您不確定是否準備增加產量以滿足分銷商的需求。

That is one difference between an API and an open-source database. In an open-source database, everything can be queried and accessed. When you set up an API for your back-end, you create endpoints that reveal only specific data.

那是API和開放源代碼數據庫之間的區別。在開源數據庫中，所有內容都可以查詢和訪問。在為后端設置API時，您將創建僅顯示特定數據的終結點。

Just like distributors are the ones that can now interact with your farm, developers from other companies are the ones that interact with your API. Once they write code that accesses data from your server, their website visitors can have new experiences based on your data.

就像分銷商現在可以與您的服務器場進行交互一樣，其他公司的開發人員也可以與您的API進行交互。一旦他們編寫了從您的服務器訪問數據的代碼，他們的網站訪問者就可以根據您的數據獲得新的體驗。

跟蹤單個API調用 (Tracking an Individual API Call)

Let’s say that you decided to set up an endpoint for eggs at your farm. A local restaurant wants to buy 1000 eggs to satisfy the 1000 omelette orders it receives each week.

假設您決定在您的農場中設置雞蛋的端點。一家當地餐館希望購買1000個雞蛋，以滿足每周收到的1000個煎蛋訂單。

Notice how our API call actually starts with a user request? That may feel a little counter-intuitive based on the description.

注意我們的API調用實際上是如何從用戶請求開始的嗎？根據說明，這可能會有點違反直覺。

An individual API call occurs when some trigger happens, and code written by another developer sends a request to your API at a specific endpoint. Your API must deliver a response based on your server-side code.

當某些觸發器發生時，將進行單獨的API調用 ，并且由其他開發人員編寫的代碼會將請求發送到特定端點處的API。您的API必須根據您的服務器端代碼傳遞響應。

In this case, the trigger is the order of 1000 eggs. The restaurant manager has already created a relationship with a farm — your farm. And, your farm has already set up the processes to deliver 1000 eggs at a time.

在這種情況下，觸發器是1000個雞蛋的數量級。飯店經理已經與一個農場(您的農場)建立了關系。而且，您的農場已經設置了一次可運送1000枚雞蛋的過程。

So, the 1000 egg order comes in, and your farm delivers the response: 1000 eggs.

因此，輸入了1000個雞蛋，您的服務器場將做出響應：1000個雞蛋。

Keep in mind, there might be 100 other restaurants that have created a relationship with your farm, and 10 of them may send a request at the same time! That is where scalability comes into play. You need to decide if your server is ready to handle that demand. But that is a topic for another tutorial!

請記住，可能還有100家其他餐館與您的農場建立了聯系，其中10家可能同時發送請求！這就是可伸縮性發揮作用的地方。您需要確定服務器是否已準備好處理該需求。但這是另一個教程的主題！

Here is the technical version of the sequence above, if you had a mapping application that could be used on other websites like Google Maps.

如果您有可以在其他網站(例如Google Maps)上使用的地圖繪制應用程序，則這是上述序列的技術版本。

Some user on another site uses your mapping application, and takes an action that requires data from your server.
另一個站點上的某些用戶正在使用您的地圖繪制應用程序，并執行需要服務器中數據的操作。
The developer on that other site has already written the code that will create a request to your API based on the action from that user
該其他站點上的開發人員已經編寫了代碼，該代碼將根據該用戶的操作向您的API創建請求
The API call comes in, and your server delivers a response.
API調用進入，您的服務器將提供響應。

Of course, there are probably 1000 other web apps that are using your mapping widget, so you need to be prepared for all those API calls!

當然，可能還有1000個其他Web應用程序正在使用您的映射小部件，因此您需要為所有這些API調用做好準備！

GET和POST的示例 (Examples of GET and POST)

Here is a quick refresher on GET and POST if you need to read up.

如果您需要閱讀，這里是關于GET和POST的快速復習。

So far, in our farm examples, the requests in our little scenario have resembled GET requests. Due to requests triggered by the restaurant’s customers, the restaurant must send a truck to your farm to pick up eggs.

到目前為止，在我們的服務器場示例中，我們的小場景中的請求類似于GET請求。由于餐廳顧客的要求，餐廳必須派一輛卡車到您的農場去撿雞蛋。

But what about POST requests? In a real world example, the Facebook API allows users of other apps to create posts, and then that app can send those posts directly to Facebook to go live immediately.

但是POST請求呢？在一個真實的示例中，Facebook API允許其他應用程序的用戶創建帖子，然后該應用程序可以將這些帖子直接發送到Facebook以立即上線。

In some cases, like social media APIs, it may make sense to allow the end-user to post directly to a social platform from a third party app.

在某些情況下，例如社交媒體API，允許最終用戶直接從第三方應用發布到社交平臺可能很有意義。

But here is another example. The Amazon API allows online store owners to programmatically post their products to Amazon’s Marketplace. In that situation, the developer on the team of the independent online store owner can also create a presence on Amazon. So, the API does not involve any sort of end user or website visitor.

但這是另一個例子。 Amazon API允許在線商店所有者以編程方式將其產品發布到Amazon的Marketplace。在這種情況下，獨立在線商店所有者團隊的開發人員也可以在Amazon上創建業務。因此，API不涉及任何類型的最終用戶或網站訪問者。

In our farm example, this is kind of like the way you might handle monthly billing. After restaurants and distributors visit your farm all month to buy products, you send them a bill at the end of the month that details the payment they must send.

在我們的服務器場示例中，這類似于您處理每月帳單的方式。餐館和分銷商整月訪問您的農場購買產品后，您會在月底向他們發送賬單，其中詳細說明了他們必須發送的付款。

Just like the restaurant must build their own processes to make sure they collect eggs at the right time, they must also have a process for paying you on time. This probably involves their accountant. Let’s say that the accountant knows that they must pay you on the first of the month.

就像餐廳必須建立自己的流程以確保他們在正確的時間收集雞蛋一樣，他們還必須具有按時付款的流程。這可能涉及他們的會計師。假設會計師知道他們必須在每月的第一天付錢給您。

Now, how might the user/customer trigger a POST request? Well, imagine that the restaurant immediately sent you a payment each time someone ordered food that came from your farm. If a person ordered a $5 omelette, and $2 of the cost came from the eggs from your farm, the restaurant would immediately send the $2 to your bank account. If this was a web app, that level of communication might work, but since this is a farming example, that would be a little impractical.

現在，用戶/客戶如何觸發POST請求？好吧，想象一下，每當有人訂購從您的農場來的食物時，餐廳立即向您付款。如果某人訂購了5美元的煎蛋，而其中2美元的費用來自您農場的雞蛋，那么餐廳將立即將2美元發送到您的銀行帳戶。如果這是一個Web應用程序，則該級別的通信可能會起作用，但是由于這是一個農業示例，因此這不太實際。

服務器場和Web應用程序之間的區別 (The Difference Between a Farm and a Web App)

As you can start to see in the last example, there is one major difference between our little farm supply chain and an API call. Timing.

正如您在上一個示例中開始看到的那樣，我們的小型農場供應鏈和API調用之間存在一個主要區別。定時。

Simply due to the logistics of the real world… we cannot hope to match the instantaneous nature of most API calls, even if the steps are generally the same.

僅僅由于現實世界的后勤……我們不能希望匹配大多數API調用的瞬時性質，即使步驟通常相同。

Let’s look at the example GET request from earlier in the tutorial.

讓我們看一下本教程前面的示例GET請求。

Here is what that means in web development terms.

這就是Web開發術語的含義。

User takes an action that triggers a request
用戶執行觸發請求的操作
Code on the server-side makes an API call to an endpoint
服務器端的代碼對端點進行API調用
API delivers specific information
API提供特定信息

But if we draw the analogy to a real-world farm:

但是，如果將此類比喻為現實世界中的農場：

User orders an omelette
用戶訂購煎蛋
Restaurant sends a truck to pick up eggs at your farm.
餐廳派一輛卡車在您的農場撿雞蛋。
Eggs are delivered to the restaurant and served in the omelette
雞蛋被送到餐廳，并在煎蛋卷中盛放

It would be incredibly impractical to send a truck to a farm to make the freshest omelette known to humankind. But, the steps are still the same. So I just wanted to mention this difference in timing.

將卡車送至農場以使人類知道最新鮮的煎蛋是非常不切實際的。但是，步驟仍然相同。所以我只想提一下時間上的差異。

But, when a user triggers a request when they use a web application, they usually get a nearly instant response.

但是，當用戶在使用Web應用程序時觸發請求時，他們通常會獲得幾乎即時的響應。

“打開您的API”是什么意思？ (What Does It Mean To “Open Your API”?)

So let’s return to our original question: What does it mean when a company “opens their API”?

因此，讓我們回到最初的問題：一家公司“開放其API”意味著什么？

It means that they have valuable data available on their server that they can now reveal via specific endpoints. The company gets to determine how developers from other companies can access their data, but at the same time, they are making it widely available in a structured way.

這意味著他們在服務器上擁有有價值的數據，現在可以通過特定的端點顯示這些數據。該公司可以確定其他公司的開發人員如何訪問他們的數據，但與此同時，他們正在以結構化方式廣泛使用它們。

In our farm analogy, this is the point when your farm decides to sell your products to distributors and restaurants, and sets up the internal systems to handle mass orders.

在我們的農場比喻中，這就是您的農場決定將產品出售給分銷商和飯店并設置內部系統以處理大量訂單的關鍵點。

喜歡本教程嗎？ (Enjoy this tutorial?)

If you enjoyed this tutorial, you will probably like the rest of my visualized guides to web development topics. Read further on the CodeAnalogies blog, or sign up hear to get the latest tutorials:

如果您喜歡本教程，則可能會喜歡我其他有關Web開發主題的可視化指南。在CodeAnalogies博客上進一步閱讀，或注冊Listen以獲取最新教程：