What Is an API and Why Should I Use One?
The acronym API is ubiquitous in the world of information technology. It represents a modern application development pattern that is extremely powerful and essential for crafting scalable and performant web and mobile applications. Developers and development teams must be able to efficiently leverage existing APIs as well as produce robust, secure, and easily consumable APIs for internal or external development. We will explore what an API is, why someone would want to make use of an API, and some great tools and methodologies to ensure that APIs are being utilized in the best way possible.
What is an API?
API stands for application programming interface. It represents a way for applications and servers to communicate and share data over the internet. Kin Lane from Postman has a great explanation of what APIs do, saying “APIs are designed for other digital systems and applications to use. Websites and APIs both do the same things, like return data, content, images, video, and other information. But APIs don’t return all the details that are needed to make things look pretty for the human eye—you only get the raw data and other machine-readable information needed behind the scenes to put the resources being delivered to work, with very little assistance from a human.” APIs make available all the same data a normal website would, but in a manner that is easy for another application to consume and transform for its own purposes. Lane goes on to say of API integration “API integration is simply the connection between two (or more) applications, programs, services, or systems, using APIs. Applications use APIs to send and receive data and content between each other.” APIs make it possible for systems to communicate, share data, and react to changes in other systems.
Why Use an API?
Understanding what an API is and what it enables, one can imagine a multitude of uses for them. APIs allow for speeding up software development projects and reducing costs. They enable developers and development teams to leverage all the hard work of development teams before them by retrieving important data from other systems that already exist. This means that a team can build on existing work to expeditiously create an application for their own purposes, pulling in relevant data from other sources that is already available.
APIs connect systems. An organization may have multiple teams working on multiple applications, and each group needs to know a subset of your organizations data to craft their application independently. A comprehensive API could allow for a CRM system and an Ecommerce system to make use of the same data without the operational overhead of constructing and maintaining different ways to interact with the same set of data. APIs allow for connected systems to react to things happening in other systems, so an order in that Ecommerce system can trigger changes in the CRM system.
APIs make it possible to decouple the heavy lifting of retrieving and manipulating data from devices and front ends. Modern JavaScript single page applications development technologies like React, Progressive Web Apps, mobile applications, and IoT devices all make use of APIs. This makes the client facing portion of the application lightweight while still being able to easily provide rich information to the user.
How to Work with APIs
Seeing how powerful APIs are, teams should be eager to make use of APIs in their organization and software development projects. This can also be daunting. Because APIs are so prevalent, to effectively leverage APIs, your development team will need to ensure that they follow best patterns and practices to ensure success. Using APIs creates challenges. They need to have the proper security so that only the right systems can get to the right data. They need to have proper documentation, so that developers of other systems can leverage the API in the way it is intended. APIs need to be maintained properly, so other systems that rely on them do not break with new changes. APIs also need to be simple; too much complexity will prevent developers of other systems from effectively leveraging that API. Fortunately, there are many tools and patterns available for developing effective APIs. These are some that the team at MercuryWorks leverage to “Make it Work”.
REST
REST stands for Representational State Transfer and is an architectural style for distributed systems. Some of the tenants of REST architecture are Client-Server which means separating user interface concerns from data storage concerns, Stateless which means that each request must contain all the information necessary to understand the request. REST sets out guiding principals that allow for systems that communicate with each other to speak the same language. It enables shared expectations for developers of different systems so that teams can lower the barrier for integrating with other systems and reduce complexity.
OpenAPI
OpenAPI is an open specification for working with RESTful APIs. It allows humans and computers to understand an API without having access to source code or documentation. OpenAPI standardizes how an API is written and documented so that it can be easily understood and consumed. OpenAPI is a great tool for promoting clarity and reducing overhead for development teams making use of APIs.
Webhooks
Webhooks are messages sent from one system to another when something happens in the originating system. This means that when systems are connected, instead of a system using an API to query information, it is notified by the system that it would otherwise query. The system that wants to be notified of changing data defines an address to be notified at over the web, and when an event happens in the originating system it sends the requested information to the system that defined the webhook. This is a powerful tool for real time information sharing across systems.
GraphQL
GraphQL is a query language for APIs that allows developers to group the data that the application needs and get all that data in a single request. GraphQL organizes data in terms of types and fields, not endpoints, which allows the application making use of the API to only care about what it needs to work. It is an abstraction for working with APIs that makes the development process simpler and more expedient.
Postman
Postman is a platform for API development. It offers tools for connecting with APIs, testing those APIs, creating documentation, automated testing, monitoring, and collaboration tools for sharing API connections with other developers on your team. The Postman API Client makes it easy to simply connect with an API and get data without worrying about your application. You can simply call an API, see the response, and ensure that it is what you are looking for before beginning development.
Swagger/Swashbuckle
Swashbuckle is a great tool that we use in applications to generate a Swagger/OpenAPI definition for an API. This examines the API that your team has developed creates documentation in the OpenAPI specification that matches your API with little additional effort. Swashbuckle also creates a page in your application for testing your API. It shows your documented API and all the endpoints and allows you to call those endpoints and test them. It can account for things like API versioning and security, and it allows for teams not only to understand what an API is intended to do, but also working with that API before programming against it.
It’s Demo Time
Swashbuckle.AspNetCore is one of my favorite tools and we use it on all our .NET Core API projects.
A link to the project can be found here: https://github.com/domaindrivendev/Swashbuckle.AspNetCore. Let’s dig a little deeper into this tool to demonstrate how easy it is to develop APIs in accordance with REST and OpenAPI principals and follow best practices of API development.
Step 1: In your .NET Core project install the Nuget package Swashbuckle.AspNetCore
Step 2: In the ConfigureServices section of the Startup.cs, register the Swagger generator.
Step 3: Make sure that the API endpoints in your project have the proper descriptors for Http and From
Step 4: In your Startup.cs Configure method add the following:
Step 5: To add the interactive Swagger page in your application, in your Configure method in the Startup.cs add the following:
Now, when you start your application, you can go to the /swagger endpoint to find an interactive page describing your application and allowing testing of your API.
There are many more options that you can make use of to customize and layer information about your API using Swashbuckle and Swagger, but I hope this example illustrates that with just a few extra steps, you can leverage tools in your application development practices ensuring proper API development practices.
Summary
API development is a powerful and essential tool for any software development team. Understanding how to produce and consume APIs came make a huge difference for a successful project. Using established patterns and practices of API development, along with making use of some great tools, helps teams quickly leverage APIs to build great systems in less time. Interested in leveraging API development for your next project? Let us help, reach out today.
Interested in Learning More?
Fill out the form below and our team will follow up shortly.