Developers and API Management

To gather insights on the current and future state of API management, we asked IT professionals from 18 companies to share their thoughts. We asked them, "What do developers need to keep in mind when managing APIs?" Here's what they told us:

UX

• They need to think about the consumer of the API, what they are trying to get done with the API, why they would use the API, and details of their use cases. There have been a lot of APIs that were built, and nobody used the APIs for various reasons such as the API was too complex, did not easily (or at all) address their use case or were poorly documented. They need to remember that just like browser or desktop software with user interfaces, APIs have a user experience and that needs to fit the needs of the consumer and hopefully delight them. 
• Have a look at multiple APIs. There is no single right or wrong way to build APIs. Look at different implementations and put yourself in the shoes of using of consuming an API to understand what works and what doesn’t. It easy to take advantage of developer portals to discover APIs, see documentation, become familiar with a lot of APIs. That’s the best way to learn. 
• Respect the process and always look for a repeatable process. No matter what style you choose, GRPC, GraphQL, REST you need to maintain consistency across the board. Treat the developer experience of APIs with the same care, respect, effort, money as UX for your applications. Developers need to focus on creating the best possible developer experience for APIs. Every developer knows what a bad developer experience is. Make sure you don’t create a bad developer experience. 
• While APIs are built for machine-to-machine interaction, they are first manipulated by developers. Developers read them, try them, wrap their heads around them, before being able to efficiently leverage them. So APIs authors must do their best to balance between efficiency and human readability. We tackle the issue by providing our customers with high-quality API clients for most common programming languages — open-source API clients that we develop, document, support. On top of that, we also develop an open-source library leveraging these clients, providing customers with building blocks for the front-end that directly offers the best end-user experience and implements the best interaction patterns with our APIs. 
• 1) APIs become a GA product once they are exposed outside of the company or even within the company. So API developers need to think in terms of a broad range of consumers and reusability when managing APIs. In doing so, best practices for development should be adopted, such as excellent documentation, understandable error messages, and predictable and consistent output and performance.
  2) Since you could have a much broader set of developers using your APIs, it’s critical to think about the developers who will be using your API as consumers vs. technical users.
  3) Because the API is reusable, backward compatibility becomes a critical consideration when updating that API. If you don’t know how, what, or when an API may be used, taking away capabilities or introducing breaking changes can create havoc for consumers. Some of the best APIs out there either enforce backward compatibility or give ample warning and time to make appropriate adjustments. 
• Decisions are easy to make and hard to reverse.  The second someone other than you is consuming your API, you have a contract with that caller not to break their code.  This means it can take literally years to unwind any mistakes you make in your interface definition.
   So, measure twice and cut once. It’s also important to be mindful of the ecosystem in which you’re publishing your APIs. What are other teams doing?  What do the existing APIs in your ecosystem look like?  It’s important that everything you do feels consistent with the rest of your API ecosystem or customers will feel like they’re consuming a bunch of spare parts rather than a consistent collection of interfaces. 
• Developers need to acquire a client-first mindset. It’s easy to start gravitating away from the end-consumer if you don’t communicate with them, but it’s vital to put the customer’s convenience first. It’s frustrating when things get out of hand due to undocumented and unspoken changes on the API provider’s side.

Microservices

• Developers need to consider API management of microservices. 86% of enterprises expect microservices to be the default application architecture in five years.

Security

• Secure every API touchpoints which are usually an afterthought — they are not taken into consideration during the design phase. Security is a key element of API lifecycle management. Given that weak API security could result in exposure to critical vulnerabilities, API security must be built into the API architecture from the beginning – it cannot be relegated as that last design consideration.

• In today’s IT environment, the pressure is on application developers to get the software to market as fast as possible. Release velocity and code complexity are increasing, which means the only way security can keep up is through automation. Developers need to consider the operational speed of their security investments because security that can’t keep up, simply gets left behind. 
• API-first design, consistency across multiple endpoints and in naming, secure without exception. Expect them to be used or discovered regardless of your intention of them being discovered or used. Use your own APIs extensively. Make sure your UI/support tools are 100% powered by your APIs. Always have a gateway in front of your services but still build security mechanisms into each service.

Other

• 1) Traditional data models you develop for APIs differ when building against a database. Realize the data that you are creating and sending out in the world and then it comes back. You have no control over it. There are different ways of developing when you have to deal with that kind of situation.
  2) APIs are still HTTP requests at the end of the day. Keeping the request/response time low is of high importance. How web 2.0 affects APIs as you start communicating over tech that’s in an always-connected mode.
• Look at API management solutions and concepts and understand why they are important. Think about problems before you run into them. Think about how to improve implementation, security, and management when you beginning a new API project. Know the current best practices of API development and management.
• The biggest challenge is understanding the full API model is an extension of the IPC model. It’s a distributed system problem, you have to think about what can go wrong, you cannot abstract away problems. Things will always break. Be able to architect a system to deal with things and gracefully degrade it is something every developer should keep in mind.
• Be able to handle any communication issues, including different responses than anticipated but also network errors (expired SSL, timeout error, DNS issues, etc). These can be quickly handled as they all come under the same kind of error ("communication error") but need to be anticipated, nonetheless. Stay informed about any changes. Most API providers issue releases notes and provide versioning to their API in order to not break their current users' integrations, but some tweaks might sometime cause a slight variation in the result that could have important consequences down the road.
• Pay attention to trends in the market. Envoy is complicated but a good way to get started. There's so much knowledge on Google and APIs and Service Mesh, take a simple application and try to play with it. Service mesh hub is everything you can imagine managing and leverage this network abstraction piece. You get the ability to debug, get visibility, canary deploy. Go to servicemesh.io and play and learn.
• Keep it simple and adopt methods like GraphQL and SPARQL. With Github, Netflix, etc. all moving to this model as well, you’ll be in good company.

Here's who shared their insights:

• Benoit Perrot , Director of Engineering,  Algolia
• Paulo Michels , E.V.P. Engineering and Co-founder,  ArcTouch
• Mike Schuricht , VP Product Management,  Bitglass
• Ryan Breen , Director of API Management,  Cimpress
• Jorge Rodriguez , S.V.P. Product Development,  Cleo
• Nick Chernets , the Founder and CEO,  DataForSEO
• Amrit Jassal , CTO and Founder,  Egnyte
• Valery Novikov , Co-founder and CTO,  FI.SPAN
• Brian Platz , Co-CEO,  Fluree
• Manoj Chaudhary , CTO and SVP of Engineering,  Jitterbit
• Derek Smith , CTO and Co-founder,  Naveego
• Rob Whiteley , CMO, and  Karthik Krishnaswamy , Senior Project Marketing Manager,  NGINX
• Mark Cheshire , Director Product Management,  Red Hat
• Cyril Nicodème , Founder,  Reflectiv
• Chetan Conikee , Founder and CTO,  ShiftLeft.io
• Idit Levine , CEO,  Solo.io
• Marc MacLeod , Founder & CEO,  Stoplight
• Rob Zazueta , Director of Digital Strategy,  TIBCO