Creating API endpoint to a Database

Important Nexla Help Center Update:

Nexla's Zendesk Help Center pages are being deprecated and will soon no longer be available.

Nexla Documentation is now the home for Nexla's User Guides, with improved formatting and categories that are easier to navigate, providing a better overall user experience.

Please update any bookmarks to the new Nexla Documentation site (docs.nexla.com/user-guides).

_______________________________________________

Nexla's Nexsets abstract incoming data and as a result allow the end user of data to access data in many different ways. For Database and API sources where Nexla can access the source in real-time Nexsets also enable a real-time API call for accessing data. Here are the steps to expose API access to your Database

Note: Currently this is a two-pass setup but is is being developed into a 1-pass setup fsoon. Contact [e-mail] or subscribe to our newsletter to learn about feature updates

First Pass

In First pass we will setup the Data Source and the API response. In 2nd pass we will decide what parameters our API call will accept

1. Start with Creating a Flow. You will be setting a flow with your Database as a source. 
2. Setup credentials for Database. Use Advanced settings to setup Bastion Host
3. Select Query Mode and enter your Database Query. You can use a query of any complexity including JOIN etc.
4. Since Nexla learns about your data by observing actual values you want a query that has Actual Results. Use the "Get Sample Records" button to see that the query is working to your expectations 
5. Now simply hit the CREATE button on top right. That's it, you have created a DataSource. Now Nexla will automatically detect a Dataset which you will see as:
6. The Detected Nexset (Dataset) holds the knowledge for Raw Data.
7. Simply hit the Send button (paper plane icon) to design your API response
8. In this Design step the question for you is:
   1. What fields do you want and what names do you want to give
   2. Do you want to transform some fields, for example hash the email id
   3. What structure do you desire. Are you creating an object structure? Simply use the dot notation in attribute naming to get the desired structure
   4. Do you want the output to be super-custom : Use Custom Python/JS functions then.
   5. Filter some data? Apply some Validations? All Nexla capabilities are available without any restriction
9. See the sample output on right to confirm if the response is expected. Click on the icon to see the JSON View                              
10. Simply hit CREATE -> Save as Dataset -> and Activate Flow
11. Congratulations! Now you have the Data Source and API response all setup

Second Pass

In this step we decide what parameters our API call with accept. As a reminder we started with this query 

1. Let's say we want the state to be a parameter. We will insert a Nexla Macro here so that Nexla knows this is a run time parameter. The setup is pretty easy if you are familiar with Nexla macros simply put a name between curly braces
2. What does this do? This tells Nexla that if the API call passes a parameter "state" then its value will be applied  here. So if user passes state=California "California" will be applied as value. If user passes "C%" then it will match all stats starting with letter C
3. Now we may want to have an API structure which has a page size and page offset as parameters. This is fairly easy and what we do is:
4. Simply save your source and back in the flow make sure everything is Activated. You are Now ready to call the API

Calling the API 

This is pretty straightforward. Use Curl, Postman, or your favorite tool to call the API

curl --location --request POST \
'https://dataops-sync.nexla.io/sync/<NEXSET_ID>?api_key=<YOUR_API_KEY>'\
 --header 'Content-Type: application/json' \
--data-raw '{"state":"New%", "pagesize":"10", "offset":"9"}' | json_pp

The response will look like so:

[
   {
      "id" : 108,
      "person_details" : {
         "gender" : "Female",
         "email" : "[e-mail]"
      },
      "first_name" : "Mella"
   },
   {
      "first_name" : "Emmett",
      "person_details" : {
         "email" : "[e-mail]",
         "gender" : "Male"
      },
      "id" : 116
   },
   {
      "id" : 124,
      "person_details" : {
         "gender" : "Male",
         "email" : "[e-mail]"
      },
      "first_name" : "Sebastiano"
   },
....

Editing your API Response

To Edit your API response simply pause the Nexset, edit the transform, Save an Activate it again. Your changes will reflect instantly

Creating Additional APIs

Do you want to create another API from the same Query for a different user? Maybe a more or less limited Data?

1. Simply Copy the Existing Nexset using the Duplicate button
2. The duplicated Nexset is an exact copy. Simply edit this Nexset, change your transforms, Save, and Activate. 
3. Call the API with the New NEXSET Id and you have a new API

Access and Permissions

API access is limited to users who have access to the Nexset. You can also make a Nexset public to give broader access 

Performance

Expecting lot of calls on this API? Don't worry Nexla will scale automatically. Want a lower latency/faster response. Contact the Nexla team to enable caching for your account/Nexsets.