MuleSoft Catalyst
Centre 4 Enablement Playbook Establishing the Foundation.
Identify Assets to Be Created and Reused Across Initial Projects
Best Practices
One of the first pieces of advice I would give to a new Centre 4 Enablement lead, after reading the MuleSoft Catalyst Methodology documentation, would be to start thinking and developing the standards, policies and patterns that will be needed to assist the integration architects, developers and testers. These documents, when complete, will form the basis of all API development and make development, testing and support so much easier than it otherwise would be. Don’t be put off by trying to get these documents complete and correct straight away, I can guarantee they won’t be, because however good you are and however much you think you understand the technology and your business, you will encounter edge cases that you will not have considered previously. I have said it before and I will say it again, perfection is the enemy of progress, adopt and live with an Agile approach and you will not only be less stressed but, in the end, you will have a better set of documentation. They will be living documents because I will give you another guarantee that technology and business requirements and capabilities will change.
So, what best practices does the MuleSoft Catalyst talk about and what advice and guidance can I give you to help in addition to the above?
The MuleSoft Centre 4 Enablement playbook lists seven API Best Practices and I will try and cover each once briefly. First the seven categories are:
- API identification
- Naming standards
- Use of standard HTTP status codes and headers
- Patterns
- RAML best practices
- API security best practices
- Authentication, authorization, policies, etc.
API Identification
This is a really important aspect to get right at the beginning of your journey with API’s. It may seem innocuous but trust me we started to get this wrong and it was having all sorts of unwanted side effects. Let me explain.
It is easy, when naming API’s in MuleSoft Exchange to use the naming conventions that you have developed for your API’s, I will come onto naming conventions soon, but this is a mistake. As with a lot of things you need to think about your customer and how they will use the API’s that you are developing. An example may explain this better:
Imagine that you have developed an API to allow timesheet data to be loaded into a time recording system. Following the 3-layer API architecture and conforming to a naming convention you may have three API’s called e-xx-tr-app, p-xx-tr-app and s-xx-tr-app (with xx identifying your organisation prefix for example). So, in your MuleSoft Exchange entry for the experience API you set the name of the experience API, the API that will most often be consumed by business customers, to e-xx-tr-app. From this I would suggest that a business customer would have a hard time identifying the purpose of the API and hence possible reuse of the API may be compromised. In this case I would suggest that the API identification in MuleSoft Exchange should be set to something like ‘Time Recording Experience API’. A very brief description of what the API does and something that is meaningful. For each API set the name to something that is meaningful to the customer of the API whether they be business users or technical users. Reuse of API’s is key so make sure it’s easy for everyone to understand what your API is there to do.
Naming Standards
I said I would come back to naming standards so here we are. Naming conventions are another key area that, when correct, can make life so much easier to both technical and business users. Naming standards need to be clear, precise, understandable and agreed by all parties. For API’s there is enough documentation on proposed standards that I do not need to cover it in any more depth here save to say that identifying the three layers of architecture along the lines of e-xx for Experience API’s p-xx for Process API’s and s-xx for System API’s will allow easy identification of where each API lies in the architecture levels. Other than that you need to look at what works within your organisation and adopt any current standards that may be in place. Probably best not to reinvent the wheel unless you have to.
Just to be clear API Identification identifies what the API is there to achieve, its function, so maybe think of it as a name that a user would use as search criteria while naming standards identify the technical name of the API and should confirm to API best practice naming standards. The difference is crucial.
Use of standard HTTP status codes and headers
A quick search of the internet will provide a list of the standard HTTP status codes and headers and I don’t think I need to say much more about this element of best practice. Unless you have very particular requirements and codes that are meaningful to your organisation or you wish to introduce custom codes to cover aspects that are not covered by the standard codes then the standard codes should meet your needs.
One thing that may be worth stating is that any codes which you introduce should be accompanied by meaningful narrative explanations where they are used in order to guide the user receiving them into the next course of action, if one is required.
Support teams should be made fully aware of any non-standard status codes used in order that they can provide the appropriate support when required.
Patterns
The establishment and documentation of patterns is another area that should be tackled as soon as possible in your MuleSoft journey and in association with any relevant parties within your organisation such as your internal Security team. The definition and publication of patterns will help to provide guidance to architects and developers, allow the standardisation of design and development and provide a template against which Design and Code governance can operate. One of the main functions of the C4E, certainly in my view, is to enforce the correct use of patterns.
To give examples of some of the patterns that I have seen we can look at the security elements required for different classifications of the data being processed by API’s and patterns that are used for connectivity between your MuleSoft implementation (CloudHub VPC, Runtime Fabric, Hybrid or PCE) and your other organisational Data Stores to name but two.
Other common patterns could be developed for Common Error Handling across all API’s , Common Logging of messages or common notifications by email for example.
RAML best practices
While I could give some descriptions or bullet points on RAML best practice I think a reference to material produced by my MuleSoft colleagues will do a much better job in this area. I would point you at the following two references where you can get more information in this area.
https://developer.mulesoft.com/tutorials-and-howtos/getting-started/best-practices-first-api-spec/
API security best practices
Each organisation will have its own security team which will set security policies and guidelines in line with their own organisations requirements and threat level. It is important that that C4E establishes and maintains a good working relationship with all aspects of the security team in order to protect the organisations data sources, infrastructure platforms, Cloud based systems and the MuleSoft Platform itself.
Security best practices will involve all aspects of infrastructure, network connectivity, API development and governance including design and code governance procedures at the appropriate times. API Security best practices will interact with Patterns as described above and the synergy between the use of best practices, patterns and governance will pay many dividends as the Centre 4 Enablement and the API Integration Services mature their offerings.
Authentication, authorization, policies, etc.
Again, authentication and authorisation and the policies associated with these will need to be addressed by each organisation and may vary by the data classification that each API is dealing with. Of course, your security team will be very interested in both and how and when each policy is applied. The Centre 4 Enablement will be required to ensure, during design and code governance, that the appropriate level of authentication and authorisation has been applied.
For those in doubt, due to the fact that authentication and authorisation sound very similar, authentication verifies the identity of a user, or in the case of an API, the service being provided by the API before granting them access to the service they are attempting to use such as another API. Authorisation determines what you are allowed to do once you have been identified. Authentication must always come before authorisation as you cannot determine what someone or some service (API) is allowed to do until you know who they are!
We have now covered the seven best practices that are suggested by the MuleSoft Catalyst Centre 4 Enablement playbook and hopefully I have convinced you of the importance in addressing each of these areas as early as possible in your MuleSoft implementation. Time spent building the foundational best practices will pay you back over time. It certainly did in our implementation. One last point though, these will be living documents and best practices, please don’t think that this is one and done, it’s not, and as with all things in life it is a constant learning and refining process.
