Blog

- October 25, 2017

Rolling out a new version of an API involves more than pushing some code to production. You probably also want to publish documentation to your users, and release client SDKs. API definitions provide you with all the tools you need to perform those tasks but really, nobody wants to generate these items manually on every release.

That’s where the GitHub integration comes in. You can now push your API definition – in the format of your choice –  to GitHub, and automate everything!

You will first need to link your GitHub account to your Restlet account. Linking your Restlet account can be done in any Restlet product and applies for all our products.

Link your GitHub account to Restlet

Open Restlet Studio and open your Account (to the right of the header bar). There, you’ll find a GitHub section in which you can link your account.

Link your GitHub account

We will never clone any of your repositories, and only ask GitHub for rights to write in your repositories, which is the minimal possible scope required for the feature to work.

Link your API to a repository

Once your GitHub account is linked, you need to link your API to a GitHub repository. Do this by opening the API you want to link and clicking on the GitHub “Link” button in the left menu.

Open API GitHub settings

Select the GitHub repository to which you want to push your API definition and select the appropriate branch and path.

GitHub API settings in Studio

In the example above, my OAS 2.0 API definition will be pushed to git@github.com:restlet/star-wars-api.git on branch 1.2.17 in folder src/main/resources.

Note: We will warn you if the repository you are pushing to is public. If this is the case, you might want to make sure there is no sensitive information in your API definition.

You can modify this configuration at any time by opening the settings of your API.

Push the API definition to GitHub

You are all set now, you just need to click on the GitHub button (that now says ‘Push’) to push your API definition to GitHub.

Restlet Client push to GitHub modal

On the CI-side

Using your prefered CI tool (Jenkins, CircleCI, …), you can now create a job that will pull the API definition from your GitHub repository and generate whatever artefacts you want.

If your CI solution allows it, you can run that job automatically each time a new version of the API definition is pushed to GitHub, or create a CRON task to run it regularly. The sky’s the limit.

CI schema Studio