Use of API Design and Management Policies

To gather insights on the state of application and data integration, we spoke with 18 executives from 15 companies who are involved in the integration of applications and data.

Here’s who we talked to:

Shawn Ryan, V.P. Marketing Digital as a Service, Axway | Kurt Collins, Director of Technology Evangelism and Partnership, Built.io | Thomas Hooker, V.P. of Marketing, CollabNet | Piyush Mehta, CEO, Data Dynamics | Daniel Graves, VP of Product Management, Delphix | Samer Fallouh, V.P. of Engineering, and Andrew Turner, Senior Solutions Engineer, Dialexa | Andrew Leigh, V.P. of Marketing and Alliances, Jitterbit | Trevor Hellebuyck, CTO, Metalogix | Mike Stowe, Developer Relations Manager, MuleSoft | Zeev Avidan, V.P. Product Management, Open Legacy | Sean Bowen, CEO, Gordon McKinney, Senior Solution Architect, Ross Garrett, Product Marketing, Push Technology | Joan Wrabetz, CTO, Quali | Razi Sharir, V.P. of Products, Robin Systems | Girish Pancha, CEO, StreamSets | Bob Brodie, CTO, SUMOHeavy |

And here’s what they told us when we asked them, "Do you have and enforce API design and management policies? If so what are they?" 

• We provide an API builder from the top down and the bottom up where the developers meet in the middle. Plan in advance how the API should look with regards to data structure. We provide management, security, who can see the fields, the content in a way that makes sense.
• Largely informal. Legacy apps are extensible. Launch of cloud platforms and cloud-based offering. API standards are evolving.
• We do not because we try to ensure any Rest or Stop-based API can work with us. We would like everything Rest-based in the future. Allows us to use API descriptors like Swagger or Raml. It’s not a top-end requirement but it makes our job a lot easier.
• Yes. A bunch of APIs that are very closed similar to Docker Compose with embedded verbs and capabilities in Rest APIs to connect into program directories. The entire app can be cloned and snapshotted. Everything in the GUI is in the API.
• We’re currently building a microservices solution for a client that uses APIs to talk to each microservice. JSON APIs standardize response formats so any API can consume it. We will be enforcing JSON API on all projects moving forward.
• We provide a traditional integration platform and a full API platform in a full stack that connects to all APIs of 90% of commercial ERPs, CRMs, ecommerce, and marketing automation platforms.
• We develop the documentation first to ensure a consistent data structure. This improves the developer experience. Documentation-first approach and Consistent Data/Response Structures are two ways to ensure you are building a better API. HATEOAS is a principle around RESTful data structures that provides additional metadata in your API responses to more explicitly define relationships. Our approach to API development is to consider the use case first, then define the implementation details that add the most value. HATEOAS is an implementation detail that can at times add value when the consuming client needs to traverse complex relationships dynamically (such as machine-to-machine integrations), but at other times adds overhead to API development for little value to the use case.
• Yes. Data collector core run time engine uses hypermedia paradigm with very rich UIs. Relevance for developers is exposed with a built-in GUI or the ability to skin their own GUI and enforce designs for dynamic and up to date UIs – another level of flexibility.
• We do have API policies.
• REST maturity models. Richardson maturity model few populations reach level 3. Few people understand or are at HATEOAS. Interfaces can be verbose and inefficient. Not always the right solutions – there are other choices. If RESTful is inefficient go with RPC over HTTP. Able to access true release tree. Get RESTful structure locally without making 10 calls. Content Delivery Networks came out of the needs for edge content delivery. REST is wonderful but we need to be responsive and reactive.
• We have standards for our own APIs and we are open to what are customers are doing. We standardize on Rest APIs for managed B2B file transfer.
• We have very strict policies. An API is no different than other user interfaces. While we have strict rules, they’re broken with every release. If you use RESTful APIs it’s less of a problem.
• 1) Absolutely. API design is one of the most critical components of the API – becoming the blueprint for success or failure.  By using specification driven development and best practices, we’re able to not only eliminate a large number of redundancies and have a hypermedia map already in place but also build an API that meets our consumers needs (and is well tested prior to writing any code). 2) While we could dive into the REST maturity levels - the reality is that according to Fielding there is only one level – your API is either RESTful or it’s not.  Sometimes we get caught up in this, but honestly that’s not what’s important.  Rather it is whether or not your API is useful, flexible, and meets your and your customers’ needs.  In other words, is it usable, does it get the job done, and will it be long lived. Of course, as you develop multiple APIs, a key to both of these is consistency (which is why API design policies become so important).  It’s this component that makes API specifications such RAML (the RESTful API Modeling Language) so critical to the success and lifespan of your API. 3) API Management likewise is critical as it provides the front-line of protection for your API, letting you know who your users are, enforce restrictions/ permissions, and prevent malicious (or accidental) attacks from reaching your underlying architecture. 
• We do for our own product.

What's your experience with API design and management policies?