API Development

Overview#

API Development is as much an art as a science. However, we do think there are some common requirements that probably need to be followed for everyone.

Besides Planning an API we offer some API Development Guidelines for you to keep in mind as you go through the API Development process.

Design for great User Experience#

There are a log of great APIs available just as there are a lot of great projects that are never fully utilized and die on the vine.

As with all development, User Experience must be a primary concern. The most successful API design enables applications developers to easily understand the purpose and functionality of the API so that they can quickly become productive and competent with using the API.

API User Experience also allows organizations to focus on getting API design right before investing in back-end implementation, which is time consuming and expensive to undo if design issues are not identified until after implementation.

The best way to design an API that developers want to use is to iteratively define the structure of the API in an expressive manner and get feedback from developers on its usability and functionality along the way. The API Designer is an example of this concept in action. The Mulesoft API Designer is an Open Source design environment that leverages RAML, the RESTful API Modeling Language. The API Designer provides an editor for drafting the APIs structure while rendering in real time an interactive console to enable interaction with the API. As the API is designed, application developers can interact with it and test its behavior, thanks to an integrated mocking service that returns the values a call to the live API would produce. Because APIs designed in RAML are concise and easy to understand, application developers can rapidly assess the APIs functionality and usability and offer concrete feedback on ways to improve it.

Optimize for use cases#

There is no such thing as a one-size-fits-all API. Even for the same underlying service or set of services, multiple APIs might be required to support different types of users and use cases. An API should be optimized to fulfill a specific business request in a specific context. Too often APIs are modeled after the design of the backend services or applications they expose instead of the use case they fulfill. This results in poor performance of the client application, poor User Experience, and ultimately, poor adoption. To optimize your API for a specific use case, think about how coarse or fine-grained it should be. For example, if you’re designing an API to enable access to sales order status from a mobile device, you need to consider the constraints of that use case.

A Mobile Device application has a higher sensitivity to number of network trips, latency and data size than a web application so this API should be designed to limit backend calls and minimize the size of data returned.

In addition, Mobile Device application use case is fairly granular – the API will lookup an order based on order number and return a status. Therefore, the API should expose this specific fine-grained functionality so it can be invoked independently. If the underlying service it accesses is coarse-grained and you anticipate building additional APIs on that service to address additional use cases, consider a tiered approach.

Expose fine-grained services that users can access directly, and add coarse-grained services on top of them to support broader use cases. Users can choose to call the fine-grained APIs directly or if they need the combined functionality of multiple fine-grained calls they can use the coarse-grained APIs. This API designed in API Designer is an example of an API optimized for this case.

Provide easy access#

Finding an audience for your API begins with publishing it to a API Portal

Build Around User Story [2]#

Imagine an API that is consumed in very different ways by each End-User.

For example, a shipping company that has an API with a Shipment resource in it. Do you think Shipment will be seen the same way by a Buyer, a Seller or the Carrier? Absolutely not!

These users have views of the Shipment resource and need to do different operations on the API.

so it goes.

If you build this API as an one-in-all solution for these three Use cases you’ll end up with an ambiguous and over-stretched API that will be difficult to evolve, hard to maintain and will expose more data than it should. In this case you should build three specialised APIs, one for each user context.

Because of the tight coupling on data level these three APIs should live in the same project, most modern web frameworks support subdomain or prefix routing, implementing it shouldn’t be a problem. Although this might sound like too much work but over time it will pay off.

The alternative to contexts would be implementing permissions or some sort of access control on the API, be wary of this approach as it adds unnecessary complexity and increases the Attack Surface.

Build a community#

The application developers who consume your API are not just your customers; they are the ecosystem that will drive the success of your API. Treating them as valued members of your community can drive significant mutual benefit. An obvious benefit of a thriving developer community is a wider reach for your API.

To support the organic growth of your API, your API Portal should include an easy way for developers to share knowledge with each other. The Notebook feature of the API Portal demonstrates this concept in action. It allows developers to document new uses they discover for your API to grow the addressable market for your API.

In addition, they can share tips and tricks in forums and even add code samples to make it easy for new developers to get started quickly with your API. Finally, a valuable benefit of community that is sometimes overlooked is that the greater the number of developers using your API, the faster bugs and issues will be identified and communicated so that you can continue to improve the value of your API.

In addition, there is great benefit in having an established communication channel with your developer community. Your API is not a static entity – as new use cases are identified and use of your API expands, enhancements and fixes are inevitable.

When you release a new version of your API, you can easily communicate the enhancements in the new version through your API Portal. You can also quickly assess who’s using each version of your API and communicate an upgrade path to them as you deprecate older versions.

Finally, understanding your developer community and having accurate insight into use cases and patterns provide invaluable knowledge that you can use to enhance your API over time.

API Auditing Monitoring Metrics Logging#

Understanding which parts of your service are being used is important, but it’s only part of the picture.

You need to see how consumers are using your API. With API Auditing Monitoring Metrics Logging for both overall usage and per consumer usage, businesses can closely monitor API activity and engagement. The ability to use API Auditing Monitoring Metrics Logging and Metric Analysis both technical and business perspectives is valuable as it helps business owners and technical teams better understand their users and ultimately create allow Continuous Improvement.

User API Auditing Monitoring Metrics Logging and Metric Analysis also show trends and changes in the environment that may indicate Cybersecurity threats or changes in how the business is operating.

Continuous Improvement#

Continuous Improvement of your API is important to keep up with the continuous changing landscape and Cybersecurity Threat Environment

Scim v2 providers#

https://drive.google.com/a/willeke.com/folderview?id=0B9YxhHKU0YhocTBtLWxxQ29FY1E&usp=sharing#

API monitoring#

API testing#

Auto-test suite

More Information#

There might be more information for this subject on one of the following:
Please see our Copyright And Intellectual Property Page and Standard Disclaimer Pages!