!!! Overview
[{$pagename}] 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|API Planing] we offer some [API] Development Guidelines for you to keep in mind as you go through the [{$pagename}] 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|https://www.mulesoft.com/platform/api/anypoint-designer|target='_blank'] is an [Open Source] design environment that leverages [RAML], the [REST]ful 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].
* The Buyer wants to pay and track the shipment.
* The Seller on the other hand is only worried about inventory and shipping fast.
* The carrier cares about the dimensions and weight of the package and its destination,
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]
* http://nordicapis.com/walkthrough-apiwares-sapience-api-security-validation-tool/
* http://nordicapis.com/monitor-the-status-of-apis-with-these-4-tools/
* http://ldapwiki.com/wiki/Auditing%20Monitoring%20Metrics%20Logging
!! API testing
Auto-test suite
!! More Information
There might be more information for this subject on one of the following:
[{ReferringPagesPlugin before='*' after='\n' }]
* [#2] - [Guys, REST APIs are not Databases|https://medium.com/@marinithiago/guys-rest-apis-are-not-databases-60db4e1120e4|target='_blank'] - based on information obtained 2018-10-13-