RESTful API

Estimated time: 25–35 minutes

This tutorial shows you how to obtain data from a third-party RESTful API. The IEX trading API (Application Programming Interface) provides real-time stock market values, news, and trends. In this tutorial you will use nio to generate a single signal with a list of recent headlines related to a publicly traded company.

  • First, you will access data served by IEX with an HTTPRequests block.
  • Then, you will manipulate data using the Join block to combine multiple inbound data signals into a single outgoing signal.

After completing this tutorial, you should be able to access and manipulate data from any API endpoint.

[info] Requests to a RESTful API

In general, an API is a set of clearly defined methods used by software components to communicate.

In the context of HTTP requests, an API is an internet resource that makes data from a database accessible via HTTP requests to URLs or "endpoints." A REST API follows a standard RESTful structure of resources and URLs.


Create service

  1. Click create new service.
  2. Complete the create new service window:
    1. In the service name box, enter get-stock-data.
    2. Click accept.
  3. Click auto-start off () in the contextual toolbar at the top of the canvas.
    • (By default, services are set to auto-start when a nio instance is started.)

Add and configure HTTPRequests block

Follow these steps to add and configure the HTTPRequests block to request news data from the online IEX API to return the last five news articles related to the Tesla stock symbol.

  1. From the available tab of your block library, search for HTTPRequests.
  2. Click the cloud icon to download the block to your instance.
  3. Drag an HTTPRequests block onto the canvas.
  4. Configure the block as follows:
    1. Name: Get IEX News
    2. HTTP Method:GET
    3. URL Target: https://api.iextrading.com/1.0/stock/tsla/news/last/5
  5. Click accept to save the changes you have made to the block configuration.

View the IEX API developer page for a breakdown of the endpoint URL.

  • https://api.iextrading.com/1.0/ is the base URL
  • /stock indicates IEX API stock collection
  • /tsla is the stock symbol for Tesla
  • /news/last/5 denotes the last 5 news articles

Add Logger block

The Logger block will allow you to see the value returned from the HTTP request.

  1. From the block library, drag a Logger block onto your canvas.
  2. Leave the default configuration and click accept to create the block.

Connect Blocks and Run Service

To see the results of your HTTP request, connect the Logger block as shown in the image below. The Logger block logs each incoming signal to the configured log level and allows you to view the signals contained in the logs.

  1. Click anywhere on the canvas to ensure you have deselected the blocks and returned to the service context.
  2. Click save in the contextual toolbar.
  3. Click start () in the contextual toolbar.
  4. Click open logger panel to view the logs.

 

Hey! The Logger Panel is Blank!

The logger panel does not contain any new logs since there are no signals driving the service. This occurs since the HTTPRequests block needs to poll RESTful APIs. In order for the HTTPRequests block to poll the API and obtain output data, it needs input signals streaming into it. (This is different than getting data from a streaming API, which you learn in the next tutorial.)


Add IdentityIntervalSimulator block

Without an incoming signal, the HTTPRequests block type won't make a request. The IdentityIntervalSimulator block type is a signal producer that emits an empty signal at defined intervals. Now you will configure the IdentityIntervalSimulator block to simulate a signal every 10 seconds.

  1. From the block library, drag an IdentityIntervalSimulator block onto your canvas.
  2. Configure the block as follows:
    1. Name: Sim 10 Seconds
    2. Seconds: 10
  3. Click accept to create the block.
  4. Move the Sim 10 Seconds block to the top of your canvas and connect it to the other blocks according to the image at right.
  5. Click save.
  6. Click stop then start to restart your service.
  7. Click open logger panel to view the logs.

 

 

What's going on there?

A signal now travels from the IdentityIntervalSimulator block into the HTTPRequests block where a request is made and data is received. Then this data will flow into the Logger block. Now you can view the signals entering the Logger block in the logger panel. Every 10 seconds, five signals display in the logger panel.

If each signal from the API was parsed into separate lines, it would resemble this format:

{
  "datetime": "2017-09-02T10:00:00-04:00",
  "headline": "Stocks to watch next week",
  "related": "ALNY,GM,TSLA",
  "source": "SeekingAlpha",
  "summary": "Key events are scheduled for the companies listed below during the upcoming holiday-shortened week. More news on: Dave & Buster's Entertainment, Inc., Hewlett Packard Enterprise, RH, Consumer stocks news, Financial stocks news, Tech stocks news, Healthcare stocks news, Top Breaking sto…",
  "url": "https://api.iextrading.com/1.0/stock/tsla/article/5182353826780468"
}

[info] Anatomy of a Signal

Each signal in a service (signals are shown inside single curly braces) conveys information through a collection of key:value pairs in the JSON format. In the example above, there are six keys or attributes on the signal: datetime, headline, related, source, summary, and url. Keys are labels, or categories, that can be shared between signals. Each key represents a value that is the signal's specific information filed under that key. When the block asks for a key, the value is received. For example, the key headline in the signal has a value of Stocks to watch next week.

 

JSON is a lightweight data-interchange format used by many APIs, databases, and signal processing languages to transfer information. The format is easy for humans to read and for machines to parse and generate.


Add and configure Join block

Sometimes raw data from the API is not in the format you need. Luckily, nio provides many block types for manipulating JSON data. Some of the most popular nio Blocks for modifying and directing data include the Modifier, AttributeSelector, Filter, Join, Replicator, and MergeStreams block types.

In this example, you will use the Join block type to simplify the request results. The Join block groups a list of signals into one signal. In this example, you will display only the "headline" part of each signal under the new key, "headlines."

The output will be formatted as a single signal with a headlines key that contains a collection of headlines:

"headlines": [<headline1>, <headline2>, <headline3>, <headline4>, <headline5>]

You will configure the Join block to return each headline in a single signal under the key "headlines."

  1. From the block library, drag a Join block onto your canvas.
  2. Configure the block as follows:
    1. Name: Join Headlines
    2. Key: headlines
    3. Value: {{ $headline }}

      Key has no {{ }} around its headlines value, as it is the string label for your new object. headlines is the new key for your joined headline collection.

      Value, however, does make use of curly braces. You want to join together the values of the "headline" key from each incoming signal. In nio, double curly braces indicate variable, or dynamic, content. Since the value of headline changes from signal to signal, you must enter an expression that represents a dynamic headline value. In this case, {{ $headline }} will be replaced with each signal's "headline" attribute and then appended to the new key "headlines."

  3. Click accept.

 

[info] nio Expressions

To indicate that something will be evaluated, use double curly braces {{ }}. The curly braces and their content are replaced with the value that the expression represents. In a nio expression, a $ is shorthand for the signal. Read more about expressions in the expressions documentation.


Insert Join and restart service

  1. Disconnect the Get IEX News block from the Logger block.
  2. Move the blocks on the canvas and insert the Join Headlines block between the Get IEX News and Logger block as shown at right.
  3. Save and restart your service to see these changes take effect.
    1. Click save.
    2. Click stop then start to restart your service.
    3. Click open logger panel to view the logs.

 

A list of the most recent Tesla headlines will display in the logger panel, as shown below. The list will automatically update every 10 seconds and reflect any changes served by the API.


Summary

You just accessed data from an external source and manipulated it to eliminate noise and extract meaningful data. You configured this service in a cloud instance of nio, but nio instances can also run on lightweight computers in a physical environment.

By adding this type of logic at the edge of a distributed system, nio is able to reduce latency and eliminate significant network burden.

With these fundamentals, nio provides you with the ability to connect to various sources of data in real time and extract the elements you need to make an informed decision.


Extra credit

Try some of the following ideas to extend or improve upon your service:

  • Insert another Logger block before the Join Headlines block to produce before and after results.
  • Try different stock symbols in the configuration of the Get IEX News block. For example, f for Ford or gm for General Motors.
  • Return the "url" instead of the "headline."
  • Return the "source" of each article instead of the "headline."
  • Experiment with the Modifier, AttributeSelector, Replicator, Filter, and MergeStreams blocks in place of the Join block.
  • Return the "summary" of each article along with the "headline."
  • Create a new simulator with a different interval that more accurately represents API updates.
  • Create a new HTTPRequests block called Get IEX Quote to return a quote from the endpoint https://api.iextrading.com/1.0/stock/tsla/quote and reconfigure the service to display the quote.
  • Make the stock symbol in URL Target dynamic to include different stock symbols as needed.
  • Manipulate the data to return the elements of a news feed including the headline, summary, and URL.

Getting help

We're always happy to help with any questions you might have about the nio Platform. View the troubleshooting guide, search the documentation, or post your questions in the forum. You can also contact live support by clicking the chat icon in the lower-right corner of the nio System Designer.

Troubleshooting tips related specifically to this tutorial are presented below.

Error Possible Cause Solution
Join Headlines.process_signals failed The Join block can not find the data it is configured to find. Make sure that the Value {{ $headline }} is singular and exactly matches the spelling of the "headline" key on the incoming signal.

 

proceed to tutorial 2: streaming API »
 

results matching ""

    No results matching ""