All Collections
API Builder/Gateway
4. API Tutorial - Route to Post New Book
4. API Tutorial - Route to Post New Book

Create an API Route to POST a new book to the database

Praise Magidi avatar
Written by Praise Magidi
Updated over a week ago

In this tutorial, you will learn how to create an API route to an endpoint that will add a book to the BookStore database.

The target route you are going to build and test should look something like this:

When executing this API request, you use a POST request loaded with the JSON Object containing the new book details, then submit the request. The response should insert a new book in the database.

For the POST Route, you will also be adding a Security Scheme to the API.

Watch the video below to learn how to create the API Route using the Synatic platform.

The following topics explain each step of the process as shown in the video.

Let's create an API

The BookStore API has already been created in the API tutorial - Part 2, so you only need to create the required Flow and Paths and then add them to the API.

This tutorial will guide you through creating a POST operation to add a book.

  1. To do this, you must first create a backing Synatic flow that will access the database to insert the data, which you then connect to the API.

  2. Then you'll create an API path and connect the Flow to the API.

  3. Lastly, you can test the Route using Postman.

Create a Security Scheme

When using the POST operation, you should secure the API, although not required, to prevent unauthorized persons or apps from writing data to the database.

Open the API Builder.

Synatic - API Security Scheme tab
  1. Click ⨁ adjacent to the Security Schemes tab to create a new scheme.

  2. Give the Scheme a name. For this tutorial, use API Key Scheme.

  3. Select the API Key authentication type. In this case, use "RESTful API."

  4. Click the Regenerate Key text button.

  5. The new key is displayed temporarily. It will look something similar to:

  6. ⚠️ Copy and keep the code in a safe place. If you lose it, you will have to regenerate it and re-assign it to all your routes.

  7. Click Save Security Scheme to confirm your scheme.

Create the backing Flow for the Create Book route

This flow requires the following steps to be configured; JSON and SQL Server.

Open the Solution menu:

  1. Click ⨁ adjacent to the Flows option to create a new Flow.

  2. Give it the name 'Create Book' and a meaningful description.

  3. Click Save to open the flow designer canvas.

Add a JSON step

Because you will be providing a JSON Object to hold the data required to add a new record to the SQL database

  1. Let's insert the JSON step from the Reader drawer in the Steps palette, as the Flow will read the JSON Object from a JSON formatted script.

  2. The JSON step opens. Click to save it as no configuration is required.

Add the SQL Server step.

  1. You will also be accessing and writing to the SQL database, so let's insert the SQL Server step from the Destination drawer in the Steps palette.

  2. Select and drag it to the flow.

  3. The SQL Server step opens.

SQL Server database connection

The connection to the database has already been created in the API tutorial - Part 2, so you just need to select the connection.

  1. Click on the SQL Server connection field.

  2. Select the BookStore Connection.

Select the Query type

Enter the SQL Query type to insert a new book into the database.

  1. Select the Insert SQL Query type.

  2. In Insert Options, enter the Object Name as 'tutorial.BookStore', the table name for the book data.

  3. In Column Mappings, enter the paths and columns with their related SQL Data Types and field length as shown below.
    - It's necessary to map the incoming data to the associated database columns.
    - The names used in the JSON data file and the database must be the same.
    - For this tutorial, it's an easy process as they are both the same.

Now click Save Step to confirm and preserve the column mappings.

Synatic - Flow Designer canvas

Test the Connection and the Query

It's always going to be a good idea, and advisable to test the query before continuing.

  1. Click the blue Run Test button on the Flow to run a simulation.

  2. Now you should add a JSON test object into the Capture Source Text code block, such as:
    "Name": "Misery",
    "Author": "Stephen King",
    "User Rating": 4.6,
    "Reviews": 9847,
    "Price": 25,
    "Year": 1971,
    "Genre": "Horror"

  3. Then click Test to execute the query.

  4. Check the response to verify that the Post was successful.

Connect the Flow to the API Route

To complete the API, the Create Book backing Flow must be connected to the API Route.

  1. Open the API Builder again.

  2. Click ⨁ adjacent to the Paths tab to create a new Route.

  3. Select the POST operation and type in the Path's name /Books.

  4. Select the Definition tab and add the API Key Scheme.

  5. Select the Source tab and then the Flow tab.

  6. Scroll to select the Flow Create Book from the available list.

Synatic - API Paths tab

Test the API Route with Postman

You can test your API endpoint using the Postman platform to insert a new book into the database.

  1. Open the API Builder again.

  2. Select the info tab and copy the Service URL.

  3. Launch Postman, select a POST request and paste the URL.

  4. Add '/Books/' to the URL.

  5. Select the Body tab and enter your JSON object:
    "Name": "Misery",
    "Author": "Stephen King",
    "User Rating": 4.6,
    "Reviews": 9847,
    "Price": 25,
    "Year": 1971,
    "Genre": "Horror"

  6. Select the RAW tab and select JSON.

  7. Click Send to execute.

The Status indicator should show 200 OK to confirm that the PUT was successful.

Synatic - API Test

Did this answer your question?