Publishing APIs
GitHub integration
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 Snapi 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.
Suppose branch main is serving an endpoint at location /sales-per-country.
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 /sales-per-country.
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 raw-site.yml file:
publishUrl: test-branch
Then all endpoints for this branch will be prefixed with /test-branch.
Refer to the YAML reference guide for more information.