Building your 1st API with RAW and GitHub

RAW provides an integration with GitHub, which allows you to manage the code and settings for your APIs in GitHub. With it, RAW automatically manages your APIs whenever you push new code or branches to GitHub. The GitHub integration is what allows individuals to manage large sets of APIs effectively, and for teams to collaboratively build and host APIs with RAW. It allows for better structuring of APIs, including versioning, testing, CI/CD, safer migrations of production APIs, and more.

To use this integration, you need to:

create a GitHub repository;
create a raw-site.yml file in the root of the GitHub repository, with repository-specific settings;
create a YAML and Snapi file with the API definition and source code;
install the RAW GitHub app on that GitHub repository, which enables the integration between the two platforms;
push code to the GitHub repository.

At this point, any changes to the GitHub repo will be automatically made visible in production. GitHub branches and pull requests are also supported for testing, CI/CD, etc.

Quickstart Guide

Let's create your first RAW API hosted in GitHub.

Step 1: Create and populate the GitHub repo

For this demonstration, let's create a new repository in GitHub and populate it with an example that contains a single API endpoint.

Create the GitHub repo

First off, we create a new GitHub repository, which we can raw-demo. If you are not familiar with GitHub and how to create new repositories, check this quickstart guide to creating a GitHub repo.

Start by cloning your newly-created GitHub repository to your local machine. If you are not familiar with GitHub and how to clone repositories, check this guide on cloning GitHub repos.

At this point, you will have an empty directory (perhaps with a README.md file) that looks like the following:

$ cd raw-demo
$ ls
README.md

Add raw-site.yml

Let's now create the raw-site file, which must reside in the root of the repository. This file is used for repository-wide configuration. The presence of this file also indicates that this is a repository with API definitions for RAW. It it does not exist, the repository will be ignored by RAW.

This file should have the following contents:

raw-site.yml
raw: "0.10"
publishUrl: demo
enabled: true

Setting enabled: true means that the repository will be published. If false, none of the endpoints are published. The publishUrl setting specifies the root base path for the API structure. It is an optional setting, and if not specified, the base path will be empty. Otherwise, the path specified in publishUrl will be prepended to the APIs you define. Therefore, in the example above, the base path for all APIs will be https://<organization>.api.raw-labs.com/demo/, where <organization> corresponds to your organization name and demo is defined in the publishUrl setting.

At this point, your repository should look like:

$ ls
README.md
raw-site.yml

Add the API code

To create an API, we must create two files:

a file with the Snapi source code for the endpoint;
a YAML file with the API endpoint definition.

First off, we create a sub-directory, called v1 for "version 1" of the API:

$ mkdir v1
$ ls
README.md
raw-site.yml
v1/

Then, we create a file called legislators.snapi in the v1 directory, with the following contents:

v1/legislators.snapi
main(state: string = ".*", legislator_type: string = ".*", party: string = ".*") =
    let
        data = Csv.InferAndRead(
            "https://theunitedstates.io/congress-legislators/legislators-current.csv"
        )
    in
        Collection.Filter(data, x ->
            Regex.Matches(x.state, state) and
            Regex.Matches(x.`type`, legislator_type) and
            Regex.Matches(x.party, party)

        )

Finally, we create a file called legislators.ymlin the v1 directory, with the following contents:

v1/legislators.yml
raw: "0.10"
endpoint: GET
code: snapi
codeFile: legislators.snapi
format: json
computeClass: normal
enabled: true
cacheSizeMB: 10
computeLimitSeconds: 20
declaration: main
metadata:
  title: Legislators of the United States
  description: search by type, party and state
  tags:
    - government
    - USA
security:
  public: true
refreshSeconds: 60

This YAML file defines the actual API endpoint, including its metadata. It also points to the codeFile that contains the Snapi source code for the endpoint, as well as the declaration name to call in the file.

The API endpoint will be published in a path corresponding with the location and name of this file in the GitHub repository (ignoring its .yml extension). Therefore, the endpoint will be published at https://<organization>.api.raw-labs.com/demo/v1/legislators, where <organization> corresponds to your organization name, demo is from the publishUrl setting of raw-site.yml, v1 is the directory name inside the GitHub repo, and legislators is the file name of legislators.yml (without the .yml extension).

At this point, your repository should look like:

README.md
raw-site.yml            => Global settings for the repository
v1/legislators.snapi    => Snapi Source code
v1/legislators.yml      => Endpoint definition

Push to GitHub

You now need to push your code to the GitHub repository, e.g:

$ git add raw-site.yml v1/legislators.snapi v1/legislators.yml
$ git commit -a "My first API"
$ git push

Step 2: Authorize RAW

We are almost done, but every new GitHub repository needs to be authorized so that RAW can read it. This is done with the RAW GitHub Repository Reader App. You need to install the App on the GitHub repository where your RAW code is kept. This way, every time you will push new code there, the App will be made aware of it by GitHub and will be able to compile the code and deploy the endpoints in RAW.

First you need to click on the [Configure] button :