The interaction with the web and data on it evolved in three stages. The first was HTML files (hyper-)linking to each other. Then came the enticing age. A user sends a request to web applications, and they process it and send out the rendered page. It is based on a template that was filled with data. There are API-s which provide data and the client can present it. These APIs don’t produce pages, page fragments, or interface elements, they only care about data. ActiveCollab was part of the first group (templating), and provided API as an add-on to the controller logic that drove web interface. It could detect that you only want the data and return it rather than rendering the page. You can add a GET parameter with the format=json argument and instead of a rendered task webpage, you will receive task details in a JSON format.
ActiveCollab, as we know it, is being broken down into two separate applications. ActiveCollab Backend is the first and only works with data. Send a request to get the data back. The ActiveCollab interface is what the Backend renders. It is written in Angular and interacts with ActiveCollab API. It is written using Angular as a standalone web application that interacts with ActiveCollab API. This is in contrast to previous versions, where the web interface was a separate part of the ActiveCollab app.
This architecture has one side effect: API provides a lot of functionality. There were many things you could do with the main web interface in the past. But API was able to accomplish more (create an invoice, run a report, etc.). The main web interface is only one of many frontends. There are many things you can do via API. It’s difficult to provide accurate and current documentation with such a wide API. Any changes in the backend eventually reach the API level so documentation must be updated accordingly. This would be a huge problem if we didn’t consider it beforehand and make API documentation an integral part the development process. Enter Narrative. This simple PHP utility can read scenario files and run them. It also validates API responses and renders documentation. It does two things. It helps us develop and test APIs during development.
It produces human-readable documentation that is based on these tests.
We can always be sure that our API is performing as expected and have up-to-date documentation thanks to Narrative. We will now regularly publish Narrative-generated documentation here:ActiveCollab API documentation
The new ActiveCollab API allows developers to control the web interface using commands. It is our most complete API. Webhooks allow your application to be notified of important events in ActiveCollab instead of waiting for updates. This reduces the load on both your system as well as ours and allows you to receive updates more quickly.
Some tasks that are typical in an enterprise setting still require access to the database or business logic level. These requirements are being met by leaving extensions points for custom reports or authentication sources. These extensions are PHP classes that are based on well-documented interfaces and have direct access the file system and database.
Conclusion