邮递员投递
We live in a truly revolutionary time.
我们生活在一个真正的革命时代。
Household items are getting smarter, services assume your behavior (and are usually right!), and things just get done… automatically.
家居用品变得越来越聪明，服务呈现出您的行为(通常是正确的！)，事情就自动完成了。
Between AI and ML rapidly getting introduced into our lives, things are progressively getting easier. More convenient. Better.
在AI和ML快速引入我们的生活之间，事情变得越来越容易。 更方便。 更好。
When my alarm goes off in the morning, I can have it trigger my towel warmer to turn on. By the time I’m done with my shower, I have a nice hot towel to dry off with. How does this happen? Is everything connected?
当我的闹钟早上响起时，我可以让它触发我的毛巾加热器打开。 等我洗完澡后，我有一条不错的热毛巾可以擦干。 这是怎么发生的？ 一切都连接好了吗？
In a sense, yes.
从某种意义上说是的。
Just about everything and their grandma has an API (Application Programming Interface) enabling access and control of certain features. With public-facing APIs becoming the norm, standards must be put in place so connecting services together is easy and intuitive.
几乎所有内容及其祖母都有一个API(应用程序编程接口)，可以访问和控制某些功能。 随着面向公众的API成为规范，必须建立标准，以便将服务连接在一起变得容易和直观。
Let’s discover how you can start bringing consistent APIs to your apps so you can join the revolution.
让我们发现如何开始将一致的API引入您的应用程序，以便您加入这场革命。
You want a place where you can design, develop, test, and observe all in one. Enter Postman.
您想要一个可以一站式设计，开发，测试和观察的地方。 输入邮递员。
Postman handles all components of the API lifecycle, providing a seamless experience for all members of a development team.
邮递员处理API生命周期的所有组件，为开发团队的所有成员提供无缝的体验。
Analysts can describe the data shape, developers can build the endpoints and connections to back-end code, QA can verify that responses adhere to the design, technical writers can build beautiful documentation in Markdown, and automation engineers can build complex workflows to test it.
分析师可以描述数据形状，开发人员可以构建端点和与后端代码的连接，质量检查人员可以验证响应是否符合设计，技术作者可以在Markdown中构建漂亮的文档，自动化工程师可以构建复杂的工作流程来对其进行测试。
Not to mention, the application allows for full source control and commenting/collaboration on almost every component.
更不用说，该应用程序允许几乎所有组件上的完整源代码控制和评论/协作。
When you decide to go API-first, what exactly are you committing to? What gives you the ability to say that?
当您决定先使用API时，您到底要承诺什么？ 是什么让您有能力这么说？
Think about your consumers for a second — both internal and external. What would they want out of an API?
想一想您的消费者-内部和外部。 他们想从API中获得什么？
Consumability 消耗性 Consistency一致性Clear documentation清晰的文件The three C’s. The consumer doesn’t care about your build pipeline or your dev practices. They care about the final product. They care about these three simple things.
三个C。 消费者不关心您的构建管道或开发实践。 他们关心最终产品。 他们关心这三个简单的事情。
Your goal as the engineering team is to provide an API that satisfies these requirements (and solves the business problem too!). You do this by putting the effort up front to provide the best experience possible when consuming your API.
作为工程团队，您的目标是提供满足这些要求的API(也可以解决业务问题！)。 您可以通过在使用API时尽一切努力提供最佳体验来做到这一点。
There are several types of APIs you can build, and Postman has the ability to handle all of them. But we want to get in with the big guns. Our API should sit side by side with companies like Google, Microsoft, eBay, and IBM.
您可以构建几种类型的API ，Postman可以处理所有这些API 。 但是我们想与大手笔打交道。 我们的API应该与Google ， Microsoft ， eBay和IBM等公司并列。
So we will make a REST API defined by the OpenAPI Specification (OAS).
因此，我们将制作由OpenAPI Specification(OAS)定义的REST API。
Adhering to a standard not only gives us an easy reference guide for formatting, but it also provides us with working examples, community support, and increased consumability due to a familiar structure. Chances are the consumers of the API have seen OAS before, and that’s exactly what we want.
遵守标准不仅为我们提供了简单的格式参考指南，而且还为我们提供了工作示例，社区支持以及由于结构熟悉而增加的易用性。 该API的使用者很可能以前就已经了解过OAS，而这正是我们想要的。
Best of all, it comes fully supported in Postman, so all we have to do is hit New -> API and fill out the form below:
最棒的是，Postman完全支持它，因此我们要做的就是单击New-> API并填写以下表格：
New API dialog in Postman 邮递员中的新API对话框With an API-first mindset, you are going to define your endpoints, the shape of the data in your requests and responses, and expected status codes before you write a single line of code.
借助API优先思想，您将在编写一行代码之前定义端点，请求和响应中的数据形状以及预期的状态代码。
With OpenAPI, this is easily manageable. In fact, the main pieces of your OAS file are paths (the endpoints) and components (requests and responses). Defining these major pieces will allow us to visualize the shape of the API and show us what we are going to be able to do with it.
使用OpenAPI，这很容易管理。 实际上，OAS文件的主要部分是paths (端点)和components (请求和响应)。 定义这些主要部分将使我们能够可视化API的形状，并向我们展示我们将如何使用它。
In my fictional business, Gopher Holes Unlimited, we want to track two main types of entities: Gophers and Holes. The first thing we need to do is figure out what the data elements are for a gopher and for a hole.
在我的虚构业务Gopher Holes Unlimited中，我们想要跟踪两种主要类型的实体： Gophers和Holes 。 我们需要做的第一件事是弄清楚地鼠和Kong的数据元素是什么。
Below is the Hole entity defined in OAS3.0, with every field given a meaningful description and an example as defined in the components\schemas section:
以下是OAS3.0中定义的Hole实体，每个字段均给出了有意义的描述，并给出了components\schemas部分中定义的示例：
You can see that the only field we require is location, but we have plenty of other properties that can be used to help define the hole.
您可以看到我们唯一需要的字段是location ，但是我们还有许多其他属性可用于帮助定义Kong。
We will do the same thing for Gopher, then move on to defining our endpoints.
我们将对Gopher做同样的事情，然后继续定义端点。
Our business is about helping people track gophers and their holes. So we need endpoints that will easily provide that kind of functionality.
我们的业务是帮助人们追踪地鼠及其洞。 因此，我们需要可以轻松提供这种功能的端点。
Add a new gopher/hole — POST
添加新的地鼠/Kong— POST
Update gopher/hole details — PUT
更新地鼠/洞的详细信息— PUT
Get a list of all gophers/holes — GET
获取所有地鼠/洞的列表— GET
Get details about a specific gopher/hole — GET
获取有关特定鼠/Kong细节- GET
Add a new status to a hole — POST
向Kong添加新状态POST
With these requirements in mind, we can build out our endpoints in the OpenAPI spec using the proper HTTP methods and REST structure.
考虑到这些要求，我们可以使用适当的HTTP方法和REST结构在OpenAPI规范中构建端点。
In the paths section of our spec, we define something that looks like this:
在规范的paths部分，我们定义如下所示的内容：
We made the endpoint /gophers, set it to be a POST, and gave it a summary and meaningful description in Markdown. We also used our Gopher entity as the definition of the body and declared some standard responses that can come back from a POST.
我们制作了端点/gophers ，将其设置为POST ，并在Markdown中对其进行了摘要和有意义的描述。 我们还使用Gopher实体作为主体的定义，并声明了一些可以从POST返回的标准响应。
Now, all we have to do is continue this format for the rest of our requirements and we’ll have ourselves a defined API! To save us some time, I’ve already done that for you and included it in the GitHub repo for Gopher Holes Unlimited.
现在，我们所要做的就是继续满足其余需求的这种格式，我们将拥有一个已定义的API！ 为了节省一些时间，我已经为您完成了这项工作，并将其包含在Gopher Holes Unlimited的GitHub存储库中。
To get the Gopher Holes Unlimited API set up in your Postman workspace, follow these steps:
要在您的Postman工作区中设置Gopher Holes Unlimited API，请按照以下步骤操作：
Fork the gopher-holes-unlimited repo and clone it onto your machine.
分叉gopher-holes-unlimited的gopher-holes-unlimited回购并将其克隆到您的计算机上。
In your Postman workspace, hit New -> API and fill out the dialog. 在您的Postman工作区中，点击新建-> API并填写对话框。 Connect the API to the OAS file in GitHub. 将API连接到GitHub中的OAS文件。 Select the API from the APIs tab. 从“ API”选项卡中选择API。 Click on the Define link. 单击定义链接。 Click the Connect Repository button. 单击连接存储库按钮。 Follow the guide to connect Postman to the repo. 按照指南将Postman连接到仓库。It’s one thing to look at a definition of an API, but it’s another thing entirely to see it in action. Once again, since we’re building this API-first, we don’t want to write any code yet. We’re still in the definition phase.
查看API的定义是一回事，而实际使用它则是另一回事。 再一次，由于我们是首先构建此API，因此我们不想编写任何代码。 我们仍处于定义阶段。
Time to use Postman for what it does best: sending web requests.
是时候使用Postman来实现其最佳功能了：发送Web请求。
With our API created and synced with the source code, we need to create a mock server that will accept requests at our endpoints and return the example values we defined in our spec.
创建我们的API并与源代码同步后，我们需要创建一个模拟服务器，该服务器将在端点接受请求并返回我们在规范中定义的示例值。
After selecting the API in Postman:
在Postman中选择API后：
Click on the Develop tab. 单击开发选项卡。 Hit Add Mock Server -> Create new mock server. 点击添加模拟服务器->创建新的模拟服务器。 Give the mock server collection a name and change the Folder Organization advanced setting to Tags. 为模拟服务器集合命名，并将“文件夹组织”高级设置更改为“标签”。 On the next screen, name the mock server and select the “Save the mock server URL as an environment variable” checkbox. 在下一个屏幕上，命名模拟服务器，然后选择“将模拟服务器URL保存为环境变量”复选框。 Hit Create Mock Server. 点击创建模拟服务器。Now we have a server stood up with examples, so we can test our API!
现在我们有一个带有示例的服务器，因此我们可以测试我们的API！
Behind the scenes, Postman built a collection with example requests and responses based on our OAS file. It also set us up a web server with the endpoints we defined and configured it to return the examples. The mock server will return responses defined in the linked collection, so be careful when you modify requests!
在后台，邮递员基于我们的OAS文件构建了一个包含示例请求和响应的集合。 它还用我们定义的端点设置了一个Web服务器，并将其配置为返回示例。 模拟服务器将返回链接集合中定义的响应，因此在修改请求时要小心！
If we click on a request in the collection, select the environment that was created for the mock server, and hit Send, we can see an example come back with the values from our OAS file!
如果单击集合中的一个请求，选择为模拟服务器创建的环境，然后单击“发送”，我们将看到一个示例，其中包含来自OAS文件的值！
Seeing the request and response details will help us get a realistic view of what it will be like to consume our API. From here, we can tinker with the definition file, regenerate the collection, and fine-tune our API!
查看请求和响应的详细信息将帮助我们更真实地了解使用我们的API的感受。 从这里，我们可以修改定义文件，重新生成集合，并微调我们的API！
When a consumer of your API is up and running, I have news for you: They don’t want to come back and maintain their integration with you. They want to set up once and have it work forever.
当您的API使用者启动并运行时，我为您带来了消息：他们不想回来并保持与您的集成。 他们希望设置一次，并使其永远有效。
Honestly, that’s not an unreasonable expectation. When I replace a lightbulb in my house, I don’t expect to go back and tighten it every week.
老实说，这不是一个不合理的期望。 当我在家里更换灯泡时，我不希望每周回去重新拧紧它。
So what does that mean for your API? Well, if you put intentional effort into making your API both reliable and backward-compatible, you are going to have happy consumers.
那对您的API意味着什么？ 好吧，如果您花大力气使API既可靠又向后兼容，那么您将获得满意的消费者。
When an API is reliable, it has high uptime and consistent results. How do you design for that?
当API可靠时，它将具有很高的正常运行时间和一致的结果。 您如何设计的？
From an API-first approach, that means we need to proactively monitor our API so we can catch any downtime before our consumers do. The easiest way to do this is with a test suite.
从API优先的方法开始，这意味着我们需要主动监控我们的API，以便我们能够在消费者采取行动之前捕获任何停机时间。 最简单的方法是使用测试套件。
In Postman, a test suite is a collection of automated requests that build on one another to execute a workflow. The response of one request contains a value we use in the next request, and so on.
在Postman中，测试套件是自动建立的一组请求，这些请求彼此构建以执行工作流。 一个请求的响应包含我们在下一个请求中使用的值，依此类推。
Test suites not only provide you with reliability, but they also give you the tools to make sure your API is providing consistent results. If the expected outcome is always going to be X, we can write JavaScript assertions in our test suite to make sure the outcome isn’t Y.
测试套件不仅为您提供可靠性，而且还为您提供了确保API提供一致结果的工具。 如果预期结果始终是X ，我们可以在测试套件中编写JavaScript断言以确保结果不是Y。
In Gopher Holes Unlimited, we want to build a workflow that automatically validates the following:
在Gopher Holes Unlimited中，我们要构建一个工作流程来自动验证以下内容：
Add a new gopher. 添加一个新的地鼠。Verify that the new gopher returns in the List All endpoint.
验证新地鼠是否在“ List All端点中返回。
Add a hole associated with the new gopher. 添加与新地鼠相关的Kong。 Set the hole status to filled. 将Kong状态设置为已填充。 Verify the hole details were updated. 验证Kong详细信息是否已更新。Using the Mock Server collection we generated earlier, we can copy and paste requests into our test suite collection to build that workflow. The collection should look something like this:
使用我们先前生成的Mock Server集合，我们可以将请求复制并粘贴到我们的测试套件集合中，以构建该工作流程。 该集合应如下所示：
Now, all we have to do is throw in some tests and chain the requests together, and we have an automated workflow!
现在，我们要做的就是进行一些测试并将请求链接在一起，并且我们有一个自动化的工作流程！
To save time, I built the test suite collection and added it to the GitHub repo. All you need to do is import the collection from the file.
为了节省时间，我构建了测试套件集合并将其添加到GitHub repo中。 您需要做的就是从文件导入集合。
With the automated workflow in place, we now just need to run it at regular intervals to make sure the API stays healthy. Once again, Postman provides an easy way to do this by creating a monitor.
有了自动化的工作流程后，我们现在只需要定期运行即可确保API保持健康。 邮递员再次通过创建监视器提供了一种简便的方法。
The monitor will run at certain times of day on specified days of the week and will report back if any of our tests failed. Below, we can see the results of running our automated tests and verify that things are healthy.
该监视器将在一周中的特定日期的一天中的某些时间运行，并且如果我们的任何测试失败都将报告。 在下面，我们可以查看运行自动化测试的结果并验证一切是否正常。
We’ve all been there: A service we love and use every day suddenly stops working. It worked yesterday but is failing today.
我们都去过那里：我们每天爱用的服务突然停止工作。 它昨天工作了，但今天却失败了。
No, the service isn’t down. They just implemented a breaking change. Whether they know it or not, they broke it for you. Now you have to go back in and change something in your integration you’ve had working for so long.
不，服务没有关闭。 他们只是实现了一项重大突破。 不管他们是否知道，他们都会为您解决。 现在，您必须返回并更改已经使用了很长时间的集成中的某些内容。
You do not want to do this with your API. You design your API with intentionality to avoid breaking changes. Obviously, the time will come when you have to make a breaking change, but you can avoid unnecessary breaks if you keep these rules in mind:
您不想使用您的API来执行此操作。 您有意设计API以避免破坏更改。 显然，总有一天你必须做出重大更改，但可以避免不必要的中断，如果你把这些规则记：
Don’t add new required fields to an API. Instead, add the fields as optional. 不要将新的必填字段添加到API。 而是，将这些字段添加为可选字段。 Don’t remove any fields. Instead, try labeling the fields as deprecated in the documentation. 不要删除任何字段。 而是尝试将字段标记为文档中不建议使用的字段。 Don’t change the shape of your responses. Adding new fields is fine, but don’t start nesting values that weren’t nested before. 不要改变回应的形式。 添加新字段很好，但是不要开始嵌套以前未嵌套的值。 Don’t rename fields. Instead, add the new name as a new field and deprecate the old field name. 不要重命名字段。 而是将新名称添加为新字段，并弃用旧字段名称。There are many ways to make breaking changes to an API, but following the four gotchas above should keep you covered for the most part.
有许多方法可以对API进行重大更改，但是遵循上面的四个陷阱应该可以使您大体上了解。
If you want to make sure you aren’t unknowingly making breaking changes, you can add a schema validation checker like ajv to your automated tests to verify that the shape of the data isn't changing.
如果要确保您不会在不知不觉中进行重大更改，则可以将ajv类的架构验证检查器添加到自动化测试中，以验证数据的形状没有改变。
Bonus: You can include your automated tests in your CI pipeline and force the build to fail if your tests fail.
奖励：您可以将自动化测试包括在CI管道中，并在测试失败时强制构建失败。
Great news! By providing descriptions and examples for every path, request, response, and schema, you’ve already made a huge dent in your API documentation.
好消息！ 通过为每个路径，请求，响应和模式提供描述和示例，您已经在API文档中大加了功。
A crucial part of an easy-to-consume API is the documentation. “What does this endpoint do? Where does this value come from? What are the acceptable values for this enum?”
易于使用的API的关键部分是文档。 “这个端点做什么？ 这个价值从何而来？ 此枚举可接受的值是多少？”
These are all questions your consumers will have when using your API. It is your job to provide them with answers.
这些都是消费者在使用您的API时会遇到的问题。 为他们提供答案是您的工作。
Out of the box, Postman generates beautiful HTML pages based on a collection. It supports Markdown at every level, offering an opportunity to make a wonderfully styled documentation page that is easy to follow.
开箱即用，Postman基于集合生成漂亮HTML页面。 它在每个级别都支持Markdown，从而提供了一个制作易于遵循的精美文档页面的机会。
If that wasn’t enough, it also provides generated code snippets for developers on how to call each endpoint in their language of choice.
如果这还不够的话，它还为开发人员提供了生成的代码片段，这些代码片段介绍了如何以他们选择的语言调用每个端点。
You can also add a custom domain on the generated documentation, meaning I can add the documentation to docs.gopherholesunlimited.com without a problem!
您还可以在生成的文档上添加自定义域，这意味着我可以毫无问题地将文档添加到docs.gopherholesunlimited.com ！
You will want to keep the documentation separate from the mock server collection, so if you navigate back to the API tab:
您需要将文档与模拟服务器集合分开，因此，如果您导航回到“ API”选项卡：
Click on the Develop tab. 单击开发选项卡。 Select Add Documentation -> Create new documentation. 选择添加文档->创建新文档。 Give the collection a name and hit Create Documentation. 为集合命名，然后单击“创建文档”。Once the documentation collection is created, you can click on the link under the Documentation section of your API and it will take you directly to the generated docs.
创建文档集合后，您可以单击API的“文档”部分下的链接，它将直接带您到生成的文档。
The documentation built by Postman will take the information from your OAS file, enrich the request in the documentation collection, then render it on the web with the following:
Postman构建的文档将从您的OAS文件中获取信息，在文档集中丰富该请求，然后使用以下内容将其呈现在Web上：
As with the mock server, you can view the generated output, update the OpenAPI spec, regenerate the collection, and view the updates on the web to fine-tune your API details.
与模拟服务器一样，您可以查看生成的输出，更新OpenAPI规范，重新生成集合以及在Web上查看更新以微调您的API详细信息。
Being a developer myself, when I see documentation like this, I know I’m working with a company that knows that they’re doing. They have taken the time to provide meaningful examples, describe every field in detail, and categorize requests appropriately.
作为我自己的开发人员，当我看到这样的文档时，我知道我正在与一家知道他们正在做的公司合作。 他们花时间提供了有意义的示例，详细描述了每个字段，并对请求进行了适当的分类。
I am just scratching the surface on the possibilities of going API-first.
我只是在探索API优先的可能性。
Adding API governance, using the Postman CLI to execute workflows at every step of the build process, and writing dedicated integration documents for third-party integrators are all ways you can extend your reach into the API-first world.
添加API治理，使用Postman CLI在构建过程的每个步骤执行工作流程，以及为第三方集成商编写专用的集成文档，都是将您的业务扩展到API第一世界的所有方法。
You have been provided the tools to design and develop your API. All you have to do now is implement it.
已为您提供了用于设计和开发API的工具。 您现在要做的就是实现它。
Best of all, once your API is implemented, you can simply swap out the url field in your environment and all your automated tests now point to the real thing! You can ensure that what you built is right because not only did you build API-first, but you also did Test-Driven Development (TDD).
最重要的是，一旦实现了API，您就可以在环境中简单地换掉url字段，并且所有自动化测试现在都指向真实的东西！ 您可以确保所构建的内容是正确的，因为不仅您首先构建了API，而且还进行了测试驱动开发(TDD) 。
Be intentional about your API design. Put your efforts into consumability, consistency, and clear documentation. Become the example other companies look to for reference. Adhere to a standard. Build something great.
谨慎使用API设计。 将您的精力投入到易用性，一致性和清晰的文档中。 成为其他公司希望参考的示例。 遵守标准。 建立伟大的东西。
**POST** /blogs { content: 'awesome', readerEnjoyability: 100, shareWithFriends: true }翻译自: https://medium.com/better-programming/api-first-development-build-consistent-meaningful-apis-with-postman-db7d1e9e8b5c
邮递员投递
相关资源：四史答题软件安装包exe