API Enablement – Learnings from the Field
Blog: BPM Blog Avio Consulting
One of the benefits of being a consultant is having the opportunity to work with a lot of different clients, many just beginning their journey with MuleSoft and API Led Enablement. In this article, I will share some of the observations and findings that I have seen that have enabled this journey to be more successful.
Understand how your APIs will be used
Sometimes we focus so much on the data that our API serves up, that we lose sight of HOW the data will be used:
- Within the business process or mobile app that uses our APIs, what are the touch points where the data is used?
- Does the consuming application have the required fields to invoke your API? If not, this may require data enrichment, etc. adding unexpected complexity that was not considered early on.
If your APIs are consumed by internal applications, collaborate with the developers of the mobile app, business process, etc. Don’t just throw the API over the wall to them and move on. Sit with them, understand how they are going to use it.
Get your APIs in front of your consumers ASAP
Once your RAML is completed, the typical next step is to publish it to the Anypoint Exchange for review and sign off. This sign off could be done by the Product Owner who validates the RAML against the success criteria that was defined for your user story. From there, you may provide the mock endpoint to the developers creating the app that consumes your API.
- Demo the API during the sprint review meeting with live data, get feedback.
- Put the alpha release out when completed, the working URL (not mock) into the hands of the developers once the sprint is completed.
- Get visibility into the effort that is building out the API consumer – mobile app, business process, etc.
- Iterate. Meet with the consumers on a regular basis to understand if the API is hitting the mark. This may also elicit other APIs that are needed as well.
Know where your data lives
Knowing where your data lives will help define the complexities of your APIs. While some may think that it resides within their enterprise databases, ERP, CRM, etc. it may be more difficult to retrieve than first thought. MuleSoft provides connectors that enable the connectivity, but must also consider the following:
- Are there multiple systems that are the source of truth for your data? If so, what is the criteria for determining where the data resides?
- How easy is it to get the data? Are there existing standards (i.e. only access data via stored procedures) that will increase complexity and effort?
- Will access to the data also provide the context of the data? Or are additional business processes needed to provide context?
Don’t try to boil the ocean
Minimal viable product (MVP) should be your mantra. Considerations include:
- Build out only the API resources needed. Not all the resources for an API may be known before releasing it. Start with what you need, add more later as needed.
- Implementation of a system API resource should be doable within a 2 week sprint, if not, it’s too complex. Refactor.
- Always build out your utility APIs first: notification, error/event logging, etc. that way you don’t have to go back and refactor APIs to use these core components.
Document your RAMLs
While developing your RAMLs be sure to add descriptions to EVERYTHING. This includes field definitions, resources, methods and the RAML itself. The easiest way for adoption of your APIs is understanding what it does, what each of the fields are intended for. Don’t expect the field name to be self-documenting. Provide context (i.e. used in fuzzy match search) in which it is used also.
Hopefully this has given you some food for thought as you begin your journey. Let us help! Our experience can help you be successful in your API Enablement journey.