Top Seven Tips for Building an API
Here are seven important tips for building an API, emphasizing the creation of a specification framework, and versioning strategy using REST and HATEOAS.
As of 2018, businesses are relying more and more on APIs to serve their clients. Microservices and serverless architectures are becoming increasingly prevalent. This creates a higher number of required API integration points to ensure a competitive advantage and business visibility.
APIs should be designed from the ground up with these needs in mind. In this article, I will discuss seven design tips for APIs that can help to meet these goals (I should note that these insights are based on my experience building APIs for mobile clients, but the lessons apply more broadly to include API designs of any type).
1. Treat Your API as a Product
A key factor when starting with any sort of development is the notion of the product. It defines the stand-alone entity that exposes useful functionality and benefits to the market. It is no easy task to design and implement an API that is easily consumable, scalable, properly documented, and secured without having a strong sense of responsibility and ownership in the process.
Thus, it's only fair that your API is treated like one, complete with its own board, backlog, and sprint plan. In addition, a product owner needs to be assigned to convey the vision of the ideal API to the agile team. Developers and testers must devise a plan to work with the best API practices and also to avoid common mistakes. As a result, the end product needs to be production-ready from day one.
2. Use an API Specification Framework
API frameworks are an attempt to standardize development processes across industries. Typically, they consist of an arsenal of tools that cover the whole development lifecycle, from concept to production. While it's true that adhering to a specification like OpenAPI/Swagger while developing an API is more opinionated, it provides better tooling interoperability. Everyone loves automation. Having the ability to generate documentation, SDKs, and UI interaction points every time the code changes is very useful. If you care about standards and want to provide conventional tools when describing your APIs, then this is a very solid option that pays back in advance.
3. Use a Versioning Strategy
Your API is your product and it evolves over time as business requirements change. As a product, it has a specific version, so clients expect the right responses. Changing a published and used API interface is a ticking bomb. The last thing you want is to introduce breaking changes without clients knowing about it. This is especially true for mobile applications when users may still have old versions installed on their phones.
There are multiple ways to enforce versioning information upon your APIs. Most API designers opt for putting the version information in the URL, as it is practical. For example, the following URL represents a customer's resource endpoint:
It is very important to stick to a version strategy that is suitable for the business and the available tooling. Later on, if you decide to change a version, it will be easier to provide warnings, updates, and other mechanisms.
4. Use Filtering and Pagination
One common mistake when developing an API is not offering a way to filter or paginate results. When you expose an API that returns a list of items that can change over time, you need to establish a pagination strategy. The reason is simple. Clients, especially mobile ones, cannot view hundreds of list items at once. For example, you can show the first 10. If your API returns the whole database listing for each request, then a lot of resources are being wasted and the performance degrades substantially.
Modern frameworks offer a way to paginate results, but you can also customize your own. A common approach is to use LIMIT and OFFSET statements on your queries. For example, see this MySQL statement for returning a slice of the total result:
This statement will retrieve rows 6-16 from the database so you can provide a JSON response that gives links to the first, next, previous, and last page of that query based on the LIMIT parameters:
5. Use REST and HATEOAS
REST is a proven and battle-tested architectural approach to designing Web services, and it is independent of any underlying protocol. Thus, it is very suitable for designing APIs. By using REST principles, you can apply some design considerations, such as:
- Treating endpoints as resources that have a conventional naming scheme. For example, if you want to expose a list of orders, you expose the following endpoint:
If you want to find a specific order, you’ll supply an ID parameter:
This has several advantages, such as better uniformity, readability, and consistency.
- Promoting stateless transactions. This helps make the services more scalable, as they won’t have the hard coupling constraints of keeping state between client and server communications.
- Easier navigation within the entire set of resources without prior knowledge of the internal URI scheme with the help of HATEOAS. It enhances the response model of each resource by providing a set of relevant links so that it is easier to interact with the API, without looking up a specification or other metadata service. One good format of HATEOAS is the HAL specification. For example, here is a HAL response to a specific article resource, exposing the relevant links for the reporters:
6. Secure Your Endpoints
You should not neglect security. Any breach can have catastrophic consequences and lead to serious legal issues. Security controls need to be established early in the development process, and, ideally, your API needs to be assessed by an external vendor. The C.I.A. triad of security applies with the following:
- Confidentiality is achieved by adding proper authentication controls that provide a means for your system to know who is accessing information or sites. OAuth2 and JWToffer a practical and secure means of authenticating controls. HTTPS must be used at all public endpoints to ensure secure communications.
- Integrity is achieved by using access controls and authorization strategies to prevent the tampering of data from unauthorized users. Role-Based Authorization provides a good option.
- Availability is achieved by establishing rate limits, partial responses and caching, in order to prevent extensive usage of API resources or even servers taken down by infinite loops.
7. Use Monitoring and Reporting
While developing and testing your API plays a big part in the process, the real work does not end here. You need to continue providing support, even before the code is deployed to production. If something goes wrong, the right people need to be notified with actionable information, in order to respond by any means necessary. This constitutes a proactive approach when developing your API. If you keep things at bay, when endpoint issues emerge, you can prevent any catastrophic failures. API monitoring tools like Runscope can also help you with that.
相关推荐
seven-tips-for-mentoring-security-newbies.pdf
09-seven-tips-for-mentoring-security-newbies
适用人群:有基础电子学技能并希望提升在设计中应对电磁干扰能力的研究人员与电气工程师。 使用场景及目标:旨在帮助工程师解决由于 LC 储能导致的问题,比如开关噪声、传导噪声等问题。通过本文档提供的步骤和技术...
The JavaMail API is an optional package (standard extension) for reading, composing, and sending electronic messages. You use the package to create Mail User Agent (MUA) type programs, similar to ...
WordPress是一款全球广泛使用的开源内容管理系统(CMS),它为用户提供了构建网站的强大平台,而"7B2 SEVEN"则是WordPress中的一个主题,由feelc8z设计和开发。这个主题以其简洁、现代化的设计和高度可定制性而受到...
"seven-fallen-api"是一个可能与JavaScript相关的项目或库,其名称暗示了它可能包含七个主要功能或组件,每个都代表一个独特的API。在JavaScript的世界里,API(Application Programming Interface)通常指的是一组...
Whether you need a new tool or just inspiration, Seven Web Frameworks in Seven Weeks explores modern options, giving you a taste of each with ideas that will help you create better apps. You'll see ...
Each language in Seven More Languages in Seven Weeks will take you on a step-by-step journey through the most important paradigms of our time. You'll learn seven exciting languages: Lua, Factor, ...
标题中的"SEVEN_SEG.zip_seg_seven_seven se"似乎提到了一个与七段数码管(Seven Segment Display)相关的项目,而"vhdl seven segment key input test progra,"描述则表明这是一个使用VHDL编程语言设计的七段数码管...
《Seven Databases in Seven Weeks》一书深入探讨了现代数据库设计与实现的多个方面,尤其聚焦于NoSQL运动中的七个数据库系统。通过一周学习一个数据库的模式,读者能够迅速掌握每个系统的特性和应用场景,从而在...
通过USB连接设备后,可以在PC上操作android设备,对于没有屏幕或者没有触屏的设备是一个很好的调试工具
**JDK 10.0.2 官方英文API详解** JDK(Java Development Kit)是Oracle公司发布的Java编程语言开发工具包,是Java开发环境的基础。版本号10.0.2是JDK的一个特定发行版,包含了对Java语言、类库以及虚拟机的更新和...
6. **Parallel Collections**: 并行集合是面向并行编程的一种抽象,它将数据结构设计为支持并行操作。例如,Java 8引入的Stream API就提供了并行处理的能力,可以充分利用多核处理器的计算能力。 7. **fibers or ...
Building Web Apps with Spring 5 and Angular 英文epub 本资源转载自网络,如有侵权,请联系上传者或csdn删除 本资源转载自网络,如有侵权,请联系上传者或csdn删除
七周七并发模型 Seven Concurrency Models in Seven Weeks 中文版 带书签完整版
【标签】:“Seven Tenets for Establishing New”指的是在新的社会背景下,为了建立健康和适应时代发展的婚姻规范而提出的一系列指导原则。 【部分内容】:文章提到了1960年至2005年间美国的婚姻和家庭变化,如...
机械设计:chapter seven belt drives.ppt
通常,一个库会包含示例代码、API文档和详细的README文件,这些都是了解和学习库功能的关键资源。如果你打算使用"seven_framework",建议查找相关的官方文档或社区资源以获取更多信息。 总之,"seven_framework"是...