农场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以获取最新教程：