As we continuously SMAX platform, there is a growing demand to achieve SMAX integrations with external systems, for use-case such as - case-exchange, collaboration tools, automation, 3rd party monitoring tools, reporting and data-extraction. For all such cases, practitioners need clear and detailed information on usage of SMAX REST APIs. While the quality of current documentation on APIs (Develop Section) has been steadily improving, but it needs to be much more structured and detailed to be effectively understood and used by field team and practitioners.
Here are some ideas where things can be improved.
- Proper listing of all the endpoint/resources and supported operations GET/POST/PUT/DELETE with payload example.
- API versioning can be incorporated to bring in enhancements and notify depreciations.
- Documentation should contain code samples (for Java, Python, NodeJS, etc) for major entities and their operations
- Would be excellent to have Swagger style API documentation and testing inside the product itself. The 'EMS Rest API' is very helpful, but needs to be matured further to reduce hit-and-trial approach.
References of few well documented APIs, which can be looked into for ideas.