APIs are published by RAW whenever the corresponding GitHub repository has a new commit or a new branch.
This relies on a GitHub mechanism called "webhooks", which notify RAW whenever a GitHub repository has any modification. RAW will then read the new state of the GitHub repository, process those changes, and then serve the new API, which reflects the latest state of the repository.
Changes are processed per branch. Within a branch, all endpoints are updated atomically. This means that the API will always reflect the exact commit state of the GitHub branch that was updated. In particular, partial updates - where some API endpoints for a branch have been updated while others have not - cannot occur. Additional, if any endpoint is invalid - e.g. contains invalid RQL or YAML definitions - then no endpoint is published either.
A branch is published if all its endpoints are valid. If any endpoint is invalid or has conflicts, no endpoint for that branch is published.
Possible conflicts and conflict resolution
Conflicts can occur when two branches (from the same or separate repositories) try to serve the same exact endpoint.
main is serving an endpoint at location
Now suppose a new branch is created, called
new-sales-api. This is a "work-in-progress" branch, that is being developed. However, this branch also includes an endpoint at location
At this point, two branches would be trying to serve the same exact endpoint at location
/sales-per-country., which means a conflict occurs. In this case, the update caused by the
new-sales-api branch would fail. That's because the
main branch is already published, and the new branch is trying to publish an endpoint that conflicts with an existing published one.
Moreover, note that the failure applies to all endpoints of that branch: if the
new-sales-api branch includes other endpoints without conflicts, those are not published either, since the entire branch is not published. This is done to ensure that APIs always represent the state of the repository, and to prevent issues where two endpoints within a branch depend on each other but some could be published while others not.
The solution to solve conflicts is to ensure no endpoints use the same location. For instance, "work-in-progress" branches can rely on the
publishUrl feature to add a prefix URL to all its endpoints, which reduces the possibility of accidental conflicts.
For instance, by adding the following to the
Then all endpoints for this branch will be prefixed with
Refer to the YAML reference guide for more information.
Monitoring API publications
To know whether an API has been published successfully, and to know the error cause in case of failure, refer to the Monitoring section of the Adminstration console.
Once APIs have been published, it is best to test them. The easiest way is to use a command-line tool such as cURL. Refer to the Invocation Details section of the Catalog console.