{"id":6889,"date":"2023-03-30T11:49:46","date_gmt":"2023-03-30T03:49:46","guid":{"rendered":"https:\/\/slash.bravefactor.com\/?post_type=resources&#038;p=6889"},"modified":"2024-02-15T16:01:21","modified_gmt":"2024-02-15T08:01:21","slug":"api-development-best-practices-a-guide-for-software-developers-companies","status":"publish","type":"resources","link":"https:\/\/slash.co\/articles\/api-development-best-practices-a-guide-for-software-developers-companies","title":{"rendered":"API development best practices: a guide for software developers &#038; companies"},"content":{"rendered":"<p><span style=\"font-weight: 400;\">The term web application programming interface (API) generally refers to mutual computer systems communicating over any given network. For example, API services offered by a server, and subsequent API offered by the client such as a web browser. The server-side of the web API equation is a programmatic interface to a defined request-response message system, and is typically referred to as the Web Service. Herein I\u2019d like to introduce some best practices to follow for API development, but first, let\u2019s review the various APIs there are to select from.<\/span><\/p>\n<h2>Choosing the right approach<\/h2>\n<p><span style=\"font-weight: 400;\">If two\u2019s company, and three\u2019s a crowd, then perhaps we should start a team as there are four key ways to make APIs; tomorrow may bring the fifth, we can only hope. I digress, the four methods we will highlight are the following:<\/span><\/p>\n<ul>\n<li><span style=\"font-weight: 400;\">SOAP<\/span><\/li>\n<li><span style=\"font-weight: 400;\">Rest<\/span><\/li>\n<li><span style=\"font-weight: 400;\">GraphQL<\/span><\/li>\n<li><span style=\"font-weight: 400;\">gRPC<\/span><\/li>\n<\/ul>\n<p><span style=\"font-weight: 400;\">Let\u2019s begin from the top\u2026<\/span><\/p>\n<h3>SOAP<\/h3>\n<p><span style=\"font-weight: 400;\">SOAP, which stands for Simple Object Access protocol, is an XML-based message protocol that enables the distributed elements of an application to communicate. SOAP can be carried over a variety of standard protocols, including web-related Hypertext Transfer Protocol (HTTP). It was developed as an intermediate language for applications that have different programming languages, enabling them to communicate with each other over the Internet. SOAP is both flexible and independent which allows developers to write SOAP application programming interfaces (APIs) in different languages while also adding features and functionality.<\/span><\/p>\n<h3>REST<\/h3>\n<p><span style=\"font-weight: 400;\">REST is an acronym for Representational State Transfer. It\u2019s a software architectural style that defines a set of constraints for creating web services. It is designed specifically for working with media components, files, or hardware devices. Its key characteristic is its use of less bandwidth which makes it quite suitable for Internet usage.<\/span><\/p>\n<h3>GraphQL<\/h3>\n<p><span style=\"font-weight: 400;\">GraphQL is an application layer server-side technology which was developed by Facebook for executing queries with existing data. It can optimize RESTful API calls, and gives a declarative way of fetching and updating your data. GraphQL can help you in loading data from server to client. It enables programmers to choose the types of requests they want to make.<\/span><\/p>\n<h3>gRPC<\/h3>\n<p><span style=\"font-weight: 400;\">In gRPC, a client application can directly call a method on a server application on a different machine as if it were a local object, making it easier for you to create distributed applications and services. As in many RPC systems, gRPC is based on the idea of defining a service, and specifying the methods that can be called remotely with their parameters and return types. On the server side, the server implements this interface and runs a gRPC server to handle client calls. On the client side, the client has a stub (referred to as just a client in some languages) that provides the same methods as the server.<\/span><\/p>\n<h2>Comparison chart<\/h2>\n<table>\n<tbody>\n<tr>\n<td><\/td>\n<td><b>Soap<\/b><\/td>\n<td><b>Rest<\/b><\/td>\n<td><b>GraphQL<\/b><\/td>\n<td><b>gRPC<\/b><\/td>\n<\/tr>\n<tr>\n<td><b>Message format<\/b><\/td>\n<td><span style=\"font-weight: 400;\">XML<\/span><\/td>\n<td><span style=\"font-weight: 400;\">JSON\/More<\/span><\/td>\n<td><span style=\"font-weight: 400;\">JSON\/XML<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Protobuf\/binary<\/span><\/td>\n<\/tr>\n<tr>\n<td><b>Payload Size<\/b><\/td>\n<td><span style=\"font-weight: 400;\">Big<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Medium<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Small<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Smallest<\/span><\/td>\n<\/tr>\n<tr>\n<td><b>Data Fetching<\/b><\/td>\n<td><span style=\"font-weight: 400;\">Might get extra data back<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Might get extra data back<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Retrieve only data you want<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Might get extra data back<\/span><\/td>\n<\/tr>\n<tr>\n<td><b>Readable message<\/b><\/td>\n<td><span style=\"font-weight: 400;\">Yes<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Yes<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Yes<\/span><\/td>\n<td><span style=\"font-weight: 400;\">No<\/span><\/td>\n<\/tr>\n<tr>\n<td><b>Community support<\/b><\/td>\n<td><span style=\"font-weight: 400;\">Widely available<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Widely available<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Widely available<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Limited<\/span><\/td>\n<\/tr>\n<tr>\n<td><b>Performance<\/b><\/td>\n<td><span style=\"font-weight: 400;\">Low performance<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Less performance<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Medium performance<\/span><\/td>\n<td><span style=\"font-weight: 400;\">High performance<\/span><\/td>\n<\/tr>\n<tr>\n<td><b>Learning curve<\/b><\/td>\n<td><span style=\"font-weight: 400;\">Hard<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Easy<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Medium<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Hard<\/span><\/td>\n<\/tr>\n<tr>\n<td><b>Founded year<\/b><\/td>\n<td><span style=\"font-weight: 400;\">1998<\/span><\/td>\n<td><span style=\"font-weight: 400;\">2000<\/span><\/td>\n<td><span style=\"font-weight: 400;\">2015<\/span><\/td>\n<td><span style=\"font-weight: 400;\">2015<\/span><\/td>\n<\/tr>\n<tr>\n<td><b>Endpoints<\/b><\/td>\n<td><span style=\"font-weight: 400;\">Single<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Multiple<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Single<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Single<\/span><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p><strong>And the Award Goes to\u2026<\/strong><\/p>\n<p><span style=\"font-weight: 400;\">For those of you who jumped ahead, I\u2019ll let it pass this time as protocol definitions are not exactly edge of your seat riveting content. I can appreciate you simply want to know which one is best, but let\u2019s give them all the credit they are due.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Alright so if you\u2019re looking for the one with the best security, perhaps you\u2019re designing for a bank or other finance based client business, then SOAP is the one you want. You\u2019ll be working in XML format, focused on server to server communication as there is no mobile integration with your API. Now the learning curve can be a little steep, but you will be rewarded with superior security.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">On the flip side of that, if you\u2019re looking for simplicity and the easiest coding path forward, then look no further than REST. You\u2019ll be working with the JSON format for messaging, and you\u2019ll also discover it feels like REST was tailor-made to work for web and mobile apps. Moreover, if you have a strict project deadline to adhere to, REST is great as the simplicity of it ensures no steep learning curve requiring ramp up time for the team initially before coding can get underway.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Now GraphQL is less commonly chosen yet still has its place in the halls of API making protocols. It\u2019s useful for optimizing the response size for mobile and web apps. This of course, will help with speeds on slower connections. As well, GraphQL is handy if you build a microservice architecture and need to merge the sub-graph.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Finally bringing up the rear, we have the formidable gRPC. This little guy will deliver both security and performance in one lean package. You\u2019re likely thinking, \u201cToo good to be true.\u201d Well I can\u2019t say you\u2019re wrong, but honestly when it comes to pure mobile and IoT devices, this is the protocol you want. However, you must accept its limitations such as a chance of a lack of browser support. Remember that the main language support is for C++, Java and so on.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">At the end of the day, the most common choice for all developers will be REST and GraphQL. REST is the most popular; however, thanks to the rise of smartphones and proliferation of mobile apps, GraphQL and gRPC have been growing in popularity in the mobile development community. So don\u2019t be hasty to select your protocol or dismiss one you have less experience with\u2026 they all play their parts harmoniously!<br \/>\n<\/span><span style=\"font-weight: 400;\">Now moving on to some best practices for your API development. The following points are a list of things to consider and keep in mind. I have found in my 10+ years of developing that though there is no perfect approach, there are certain boxes you can tick to ensure best practices in developing APIs. So, let\u2019s dive in, shall we?<\/span><\/p>\n<h3>SSL for security<\/h3>\n<p><span style=\"font-weight: 400;\">SSL as you may know stands for Secure Socket Layer. The clear difference between the URL of an API running over SSL and one which is not is the \u201cs\u201d clearly visible after HTTP. SSL plays a crucial role for security in any API design. It does exactly what you would expect; that is, secures your API making it less vulnerable to malicious attacks. This is a good first step, but other security measures should be taken. Those can include ensuring the communication between the server and client is private, and confirming that anyone consuming the API doesn\u2019t get more than what they request.<\/span><\/p>\n<h3>API documentation<\/h3>\n<p><span style=\"font-weight: 400;\">An API documentation or specification is like a template of your future docs, the unified language that describes the design of your API, explains how it functions and what to expect from it. There are a few specifications, such as RAML (RESTful API Modeling Language), OpenAPI (formerly Swagger), and API Blueprint.<br \/>\n<\/span><span style=\"font-weight: 400;\">One of the most useful tools, and free to use, for API documentation is Swagger. Alongside your documentation you have the option to use Postman which can be a solid testing tool in software development to correctly test your APIs; though, keep in mind Postman is a bit pricey to use, yet there is no question to the value it provides.<\/span><\/p>\n<h3>GraphQL federation<\/h3>\n<p><span style=\"font-weight: 400;\">This only applies to those of you who select to use the GraphQL API type. Federation is a powerful tool with an open architecture for creating a supergraph that combines multiple GraphQL APIs. Each microservice you have in your software gives you a separate endpoint so, the best practice in the case of using GraphQL, is to merge all the subgraphs into one supergraph.<br \/>\n<\/span><span style=\"font-weight: 400;\">Through using Federation, you can responsibly share ownership of your supergraph across any number of teams. This holds true even if you currently only have one GraphQL API; Apollo Federation is essential for scaling that API as you grow your features, user base and organization.<\/span><\/p>\n<h3>Regarding CI\/CD<\/h3>\n<p><span style=\"font-weight: 400;\">Now for a short word on the CI\/CD. I personally recommend using a schema registry, and there are three good options available to select from. You may decide which suits the API development best practices for your project.<\/span><\/p>\n<h3><a href=\"https:\/\/www.apollographql.com\/docs\/graphos\/\" rel=\"noopener\">Apollo studio<\/a><\/h3>\n<p><span style=\"font-weight: 400;\">One key point to consider when opting for Apollo is that it\u2019s not open source. Apollo is SaaS run on a cloud platform. There is no setup or maintenance which makes this a very cost effective solution, and your sub-graph should be publicly accessible. If security is of concern and you would like to host the Apollo gateway in your infrastructure, this option may not be the most suitable for you. The enterprise solution version certainly adds powerful options, but comes at a hefty cost and self-hosting is not an option.<\/span><\/p>\n<h3><a href=\"https:\/\/github.com\/tot-ra\/graphql-schema-registry#graphql-schema-registry\" rel=\"noopener\">GraphQL-schema-registry by Pipedrive<\/a><\/h3>\n<p><span style=\"font-weight: 400;\">On the other hand we have this option presented to us by Pipedrive. It\u2019s open source which is attractive, but there is no SaaS option available. As well, you are limited to self-hosting.<\/span><\/p>\n<h3><a href=\"https:\/\/the-guild.dev\/graphql\/hive\" rel=\"noopener\">GraphQL hive<\/a><\/h3>\n<p><span style=\"font-weight: 400;\">Finally to round out the three, there is GraphQL from Hive. Again this one follows the previous as being open source, but it includes a SaaS option that comes with no setup or maintenance. This makes it a very cost effective solution as you can also host Apollo gateway in your infrastructure. It does include a self-hosting option.<\/span><\/p>\n<h2>Tests are your friend, so, test often<\/h2>\n<p><span style=\"font-weight: 400;\">This guide wouldn\u2019t be complete if I didn\u2019t mention testing; for we all know that all best practices require proper testing. API development is no different and you will be best served to factor for frequent testing sessions. This will help you in understanding how each new feature impacts its functionality and subsequently you can then address potential security vulnerabilities.<\/span> <span style=\"font-weight: 400;\">The broad range of available API testing tools covers many scenarios and includes popular tools like Postman, SoapUI, Katalon Studio, and Swagger.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Moreover, one useful method is the BDD (Behavior-Driven Development) approach. This is one of the software development techniques that has emerged from TDD (Test-Driven Development). The principle of BDD testing is that test cases are written in a natural language that is easily readable by non-programmers as well.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">One simple example is using Cucumber as a tool of BDD. <\/span><span style=\"font-weight: 400;\">Consider the following s<\/span><span style=\"font-weight: 400;\">cenario: the user wants to login to the system. The given user launches the login screen. When the user enters the username, password and submits, then a \u201cLogin Successful\u201d message appears.<\/span><\/p>\n<h2>API observability<\/h2>\n<p><span style=\"font-weight: 400;\">Concerning API observability, there are four key points to note herein. Those are monitoring, logging, visualization and tracing. Monitoring is collecting, processing, aggregating, and displaying real-time quantitative data about a system, such as query counts and types, error counts and types, processing times, and server lifetimes. This also includes alerts on anomalies.<\/span><\/p>\n<ul>\n<li><span style=\"font-weight: 400;\">Tracing is the ability to follow user requests through the system, even across microservice boundaries, using techniques such as correlation ids.<\/span><\/li>\n<li><span style=\"font-weight: 400;\">Logging is collecting system and application logs, in a standard structured format, from servers and services in a cluster. Good logging solutions enforce consistent logging formats for improved parsing of logs. Good logging solutions also include extra details such as correlation ids so it is possible to trace user requests across microservice boundaries.<\/span><\/li>\n<li><span style=\"font-weight: 400;\">Visualization is the process of querying for different subsets of data, aggregating as required, and then displaying on charts for easier interpretation of data.<\/span><\/li>\n<li><span style=\"font-weight: 400;\">Tracing is the ability to follow user requests through the system, even across microservice boundaries, using techniques such as correlation ids.<\/span><\/li>\n<\/ul>\n<h2>Purpose: observability vs monitoring<\/h2>\n<p><span style=\"font-weight: 400;\">Monitoring is about being aware of things we know can go wrong; that is, increases in latency, spikes in error rate, or hosts disappearing and so on. Observability comes into play when unexpected things happen and helps us understand why. Observability is a quality of software, services, platforms, and products that allows us to grasp how systems are behaving. It makes investigating and diagnosing problems easier; the more observable a system is, the quicker we can comprehend why it\u2019s acting up and fix it.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">For example, monitoring will tell you whether the system works whereas observability lets you ask why it\u2019s not working. Both are useful tools and should have their place in your toolbox as it is. Remember, you\u2019re only as good as the tools you\u2019re working with, but your best practices can make your APIs polished pieces of coding artwork!<\/span><\/p>\n","protected":false},"featured_media":11020,"parent":0,"template":"","resource-topic":[55,63],"resource-type":[43],"class_list":["post-6889","resources","type-resources","status-publish","has-post-thumbnail","hentry","resource-topic-minimum-viable-product-development","resource-topic-software-development","resource-type-articles"],"_links":{"self":[{"href":"https:\/\/slash.co\/wp-json\/wp\/v2\/resources\/6889","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/slash.co\/wp-json\/wp\/v2\/resources"}],"about":[{"href":"https:\/\/slash.co\/wp-json\/wp\/v2\/types\/resources"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/slash.co\/wp-json\/wp\/v2\/media\/11020"}],"wp:attachment":[{"href":"https:\/\/slash.co\/wp-json\/wp\/v2\/media?parent=6889"}],"wp:term":[{"taxonomy":"resource-topic","embeddable":true,"href":"https:\/\/slash.co\/wp-json\/wp\/v2\/resource-topic?post=6889"},{"taxonomy":"resource-type","embeddable":true,"href":"https:\/\/slash.co\/wp-json\/wp\/v2\/resource-type?post=6889"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}