How to build and host (for free!) an API that shares data from a XML file using RAW

In this example, we are going to build an API that reads data from a XML file. This data will then be hosted as a REST API. For this, we are going to be using RAW, a platform to quickly build and host APIs.

Let's get started!

info

If you are familiar with RAW and want to deploy this endpoint on your account, click below:

API over XML file

Search for a person by name.

Overview

Sample usage:

/api/xml[?name=<person_name>]

For instance, to get the information about bob use:

/api/xml?name=bob

Code

main(name: string = null) =
    let
        people = Xml.InferAndRead("https://raw-tutorial.s3.amazonaws.com/inference/people.xml")
    in
        Collection.Filter(people.person, (x) -> Nullable.IsNull(name) or x.name == name)

Create a blank API endpoint in RAW

Once you login to RAW, you should head up to the 'Workspace' section as shown below.

Then, click on 'Add Endpoint' to create a new endpoint and choose a new 'Snapi' as shown below. You could also choose an existing template, but for this example, let's start blank and write the code ourselves.

Write the endpoint code

Now that you have a blank endpoint, let's start writing some code. Before we start, here's an overview of the RAW Workspace.

Now let's follow in steps:

Step 1: Write the code

In RAW, endpoints are written in Snapi, a simple-to-use programming language specifically created specifically for building APIs. You will see this is very simple to create.

Let's copy/paste the following code for our endpoint (see figure, as step '1'):

main(name: string = null) =
  let
    people = Xml.InferAndRead("https://raw-tutorial.s3.amazonaws.com/inference/people.xml")
  in
    Collection.Filter(people.person, 
      x -> Nullable.IsNull(name) or x.name == name)

// The following test will run if you press the play button.
main("bob")

Don't worry if you don't follow all the code just yet. This will be explained in detail below.

Step 2: Test the code

Next, let's test the code. Click on the play button (shown in the figure as step '2') and you will have a live preview of the result of calling the last line of the code.

Step 3: Choose the final URL

You can choose the exact path where your API will be hosted. This is shown in the figure as step '3'.

Step 4: Edit the metadata

Optionally, you can edit the metadata metadata (shown in the figure as step '4'). The metadata is important since RAW includes a built-in API Catalog that helps you and your users find API endpoints later.

Step 5: Deploy the endpoint live!

We are almost done. Now click to deploy your endpoint (shown in the figure as step '5').

Congratulations, your API is now published! It will be served right away and visible in the API Catalog as well.

How does the code work?

Let's look closer at how the Snapi code works!

main(name: string = null) =
  let
    people = Xml.InferAndRead("https://raw-tutorial.s3.amazonaws.com/inference/people.xml")
  in
    Collection.Filter(people.person, 
      x -> Nullable.IsNull(name) or x.name == name)

// The following test will run if you press the play button.
main("bob")

• Line 1 defines the main method. Its arguments will become query parameters in the URL call. These arguments all have default values (null to be precise), which means they are optional arguments. The value null (i.e. not defined) will be handled later during the filtering operation.
• Line 3 defines the file that contains the data. It is an XML file.
• Line 5 applies a filter. This will filter the XML file so that we are left only with the rows whose values match the arguments (if defined).
• The filter condition is defined in Line 6. The pattern Nullable.IsNull(name) or x.name == name) is used to apply the filter on names only if the name value was defined by the user. The Nullable.IsNull(name) will return true if the value is null. Otherwise, if the value is not null it means the user passed a name argument to filter on; in that case we check that x.name == name.
• Line 9 defines the test to run when the play button is pressed.

Let's improve this API!

Now that you understand the basic concepts, there's many improvements that can be done. Below is a list of pointers:

• To secure the endpoint, read this guide.
• To improve performance with caching, read this guide.
• Learn how to invite users.
• To create API keys, read this guide.
• If you prefer, paid plans have access to GitHub integration, which allow teams to collaboratively build code together, write test suites, and provides a complete CI/CD flow.

What's next!

Take a look at other examples, or join us in our Community to learn more!

Ready to try it out?

Pick a template!

Otherwise, if you have questions/comments, join us in our Community!