Forem: Superface

LLM Function Calling - The same... But different

Martyn Davies — Thu, 11 Apr 2024 12:27:57 +0000

In the ever-expanding world of LLMs, "function calling" allows you to define custom functions that a model can use to extend its functionality and knowledge by giving it access to external APIs.

These functions help supply data and abilities that Large Language Models typically don't know about, such as (but certainly not limited to):

Real-time data or current events
Personal information, such as calendar appointments, emails, todo list items
Business informatics, such as sales data, customer information, or support queries
The ability to act upon data and make changes to or update information stored elsewhere

These functions, or "tools" as they are sometimes referred to, are provided to the model as a function description. This description tells the model everything it needs to know about what the function can achieve and what it needs to know to achieve it.

How function calling works

Step-by-step, almost all models follow this approach:

User submits a prompt
Prompt is submitted to an application responsible for handling the communication between the user and the model, along with one or more tool/function definitions. These are both passed to the model.
The model chooses a function that suits the execution of the user prompt
Model returns the chosen function name and values to the application
Application executes the function and returns the API response to the model
The model uses this response to determine the prompt response
Response is returned to the user via the application

LLMs don't execute functions at all (although this might change in the future). For now, an application must bridge the user and the model. This application will have the logic to execute any functions the model chooses.

Function calling overview

Let's take a look at how these tools are implemented in some of the major models, because altough conceptually the same, there are some small, and frustrating differences. To help with the comparison we'll use the ever popular "Get the current weather in..." example.

OpenAI

The first of the most recent crop of LLMs to implement function calling in their API for their gpt-3.5-turbo-0125 and gpt-4-turbo-preview models. They also allow users to build tools into their custom GPTs in the form of GPT Actions using Open API Specifications, which we won't cover here.

OpenAI expects any tools you want the model to be aware of to be defined using a JSON schema aligned with the Open API JSON schema:

[
  {
    "type": "function",
    "function": {
      "name": "get_current_weather",
      "description": "Get the current weather in a given location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, e.g. San Francisco, CA"
          },
          "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
        },
        "required": ["location"]
      }
    }
  }
]

MistralAI

Great news! Mistral's JSON schema for tools is the same as OpenAI's. This means any function descriptions you have defined for one will work with the other without any changes.

Additionally, Mistral differentiates tool choice responses using a special purpose role of tool to keep them separate from the user and assistant roles. OpenAI also uses this approach.

Anthropic Claude3

Claude is the latest LLM to support function calling via API (in Beta as of April 2024). Again, the approach is the same, but unlike OpenAI and MistralAI, there are some differences to be aware of.

The first is with the schema. On the surface, it looks almost the same, but it isn't. Here, there is no requirement to declare a function object first, and the parameter definition lives in an object called input_schema rather than parameters.

Outside of that, the definition schema is the same. Some tweaking will be required to use tools that have previously been defined for OpenAI or MistralAI.

{
  "name": "get_current_weather",
  "description": "Get the current weather in a given location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city and state, e.g. San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

The second difference is in how the tool choice responses are differentiated. Anthropic's APIs use a pattern of alternating user and assistant messages, each containing an array of content blocks like text, image or tool_result.

In this format, any responses your application gets from an API when executing a function can be passed back to the model using the user role. The data is contained in a tool_result content block to aid with differentiation.

Cohere Command-R

The Cohere team's Command-R model also supports function calling. Again, the approach is similar to all of the above models, but the function definition schema is slightly different.

[
  {
    "name": "get_current_weather",
    "description": "Get the current weather in a given location",
    "parameter_definitions": {
      "location": {
        "description": "The city and state, e.g. San Francisco, CA",
        "type": "str",
        "required": True
      },
      "unit": {
        "description": "The unit of temperature, either 'celsius' or 'fahrenheit'",
        "type": "str",
        "enum": ["celcius", "farenheit"]
      }
    }
  }
]

Cohere's API expects an even leaner function definition that removes some of the extra explicit typing used by Anthropic, Mistral, and OpenAI and gets right into the parameter_defintions.

Unlike the others above, where required parameters are listed in a specific required array, Cohere expects that any necessary parameters are identified explicitly. This approach to the schema likely means that Cohere does not follow the Open API JSON schema approach used by the other models.

Google Gemini 1.0 Pro

Gemini's function calling approach follows the Open API JSON schema for function definitions, which means that using the same weather example as OpenAI and MistralAI would also work out of the box without any changes.

Others

These are just some of the models that now support function calling, but they are by no means a complete list.

You'll also find the functionality available in other models, such as Llama-34b, which can be used via Together.ai, Fireworks AI's Firefunction v1, and there are no doubt many more to come.

Observations

Most LLMs are sticking with using the Open API JSON schema as the basis for their definitions, which, given the early nature of this functionality, is encouraging as it allows for a relatively high level of cross-compatibility.

This cross-compatibility presents an opportunity for developers, allowing them to switch models based on many factors, including use case, cost, speed, and training.

With ever-expanding, community-powered development frameworks such as LangChain adding binding for function calling in more and more models every week, the time to implementation is getting shorter all the time.

Superface & Function Calling

If you like the idea of working with function calling in your application or agent, but want to save time on building function descriptors for tools and more functions to work with their APIs, Superface's Hub API is exactly what you need.

Using the Hub API you automatically get function descriptions for any tools that have been added to your Superface account. These function descriptions can be used by OpenAI, MistralAI, Anthropic, and LangChain.

The Hub API also allows you to securely authenticate users so they can provide their own credentials for any of the tools that Superface offers, inside your agent or application.

For more information on how to implement this in your application, check out our documentation, or drop us an email at support@superface.ai, and we'll gladly tell you more.

Connect a GPT Action to SaaS using Superface

Martyn Davies — Mon, 22 Jan 2024 13:33:18 +0000

When combined, custom GPTs and GPT Actions offer many possibilities. Any GPT that can connect to services outside of ChatGPT immediately becomes more powerful, and the scope of what they can achieve is vastly increased.

GPT Actions

A custom GPT is connected to other services using GPT Actions. These actions allow the GPT to connect to APIs through an Open API Specification, which represents the endpoints the API has to offer and the required inputs, expected outputs, and authentication requirements.

This is great, but this implementation has some downsides once your ambition goes beyond a few endpoints into many endpoints from many different APIs. You will soon find yourself cold and alone down the schema rabbit hole, wondering what you’re missing in the outside world.

Let’s face it: you want to build GPTs, not Open API Specifications, right?

One Action. Many APIs.

We created Superface to help with this problem by enabling you to connect popular SaaS platforms and other APIs to a central hub that can be used in your custom GPT by connecting a single GPT Action.

With Superface, you don’t have to worry about creating or managing Open API specifications because we provide and maintain them on your behalf, regardless of how many platforms you have connected and whether you used our pre-built connectors or added your own.

Connecting a GPT to Superface

Let’s say you want to connect a GPT you are building to some of the platforms you and your colleagues use regularly so that you can have a single interface for all the different pieces of information and queries.

Start by setting up an account with Superface. You can try it for free.

Once logged in, you will be guided through the steps you need to connect your GPT Action to Superface. We outline them in the Superface documentation, but those steps are:

Add an Action to your GPT
Set up the authentication
Import the schema from Superface

To ensure you have your connection between your GPT and Superface set up correctly, we ask you to add our Wttr.in tool (Who doesn’t want to ask about the weather, right?) which is then added to your initial schema and available to use immediately so you can test your connection.

Adding a GPT Action for Superface

Connecting your custom GPT to Superface takes just a few moments, once you find the Actions settings section. It's not most visible button in the GPT configuration, hiding out at the very bottom of the page.

Start by adding an Action to your GPT.

The GPT Actions setup page in your Superface account gives you the three pieces of information you need to get the Action set up in ChatGPT.

The authentication information
The URL to use to import the schema to your GPT
A privacy policy URL (which automatically updates when you add new tools!)

You can test the connection using the Wttr.in prompt suggested on the Superface GPT Action setup screen. If everything is working correctly, you'll see that Superface connected successfully.

Your GPT is now set up and connected to Superface. It's time to add some tools.

Adding Tools to Superface

Superface offers a selection of ready-to-connect APIs for popular platforms such as G Suite, Zendesk, Slack, Jira, GitHub and many more.

Click to add any of the tools you want your GPT to access.

Some tools, such as Google or GitHub can be authenticated with single sign on. Others, such as Jira, and Zendesk require that you set up and provide an API key that Superface can use to access those services.

Please note that every time you add or remove a tool in Superface, you will need to re-import the schema in your custom GPT Action settings. You can use the URL provided in Superface's GPT Actions section to do this.

Your feedback is important

After implementing Superface as a GPT Action we would love to hear your feedback on how it's working for you. Feel free to drop us an email on support@superface.ai with any suggestions, improvements or tool requests.

Integrate APIs using AI via CLI

Martyn Davies — Mon, 05 Jun 2023 07:54:35 +0000

Imagine a workflow that allows developers to focus on building great applications, rather than getting bogged down in the details of integrating with third-party services. What if something else could read and understand the documentation for them?

That workflow is coming. We’re excited to share the first technology preview of the new Superface CLI.

The CLI (which we fondly refer to as EDGAR) is a powerful tool that allows developers to integrate with third-party APIs directly from the command line. Designed to help developers save time and effort by providing them with a powerful AI analysis that allows them to generate working integration code for their applications using the documentation of the provider they want to integrate with.

You can see more about how it works in the technology preview video below.

How the Superface CLI works

Superface harnesses the power of AI to analyze API documentation.

Currently, APIs defined with an Open API Specification (OAS) document, or hosted by Readme.io, can be ingested but we’re soon going to allow you to provide any documentation you want, in any text based format you have.

Below we ingest the OAS for the Resend.com email API directly from a GitHub repo.

npm run ingest https://raw.githubusercontent.com/resendlabs/resend-openapi/main/resend.yaml

Once ingested into the system, you can create working integration code for your desired API by stating the use case you want to achieve. For example, “send an email”, “return geolocation from an IP address” or “translate from English to Czech”.

npm run profile resend "send an email"

With this use case, Superface will analyze the documentation and create a plan for how the API should be used in order to achieve it. The map command starts this process.

npm run map

This plan can then be turned into working integration code that runs via the Superface OneSDK. It’s important to highlight that this isn’t chatbot-to-code, as you have full code-like control over the files that are generated and can edit them to tune the output should you need to.

Additionally, we’ve included a specific command that allows you to run what the CLI generated against the third party API you want to work with, to check that it works and show you a real success or failure response.

npm run execute ./email-communication/email-sending/email-communication.email-sending.resend.map.js

This will run the code the CLI generated for you directly against the API, with no middleman or proxy, and output the response.

Overall, creating the integration you want breaks down to just 4 steps:

Ingest the API documentation into the system.
State the desired use case (e.g. "send an email").
Superface will analyze the documentation and generate a plan for how to call the API to achieve the use case.
The plan is turned into working integration code that runs via the Superface OneSDK.

At this time, all of these steps can be completed using the CLI, using AI to give you full, fast, control over your API integration workflow.

Register for early access

Superface CLI will soon be available for early access users. If you'd like to try it, go to superface.ai/cli and let us know. We're excited to hear what you think.

Subscribe to get early access

Let's build a Google Maps clone with React, Leaflet, and OneSDK

Dexter — Mon, 15 May 2023 09:23:46 +0000

We will build a project similar to Google Maps. The project will cover some basic features of Google Maps, like pinpointing specific locations on the map or planning of routes between locations. Moreover, users can use geocoding to lookup the location of a postal address.

We will use React and React Leaflet on the frontend, and Node.js, Express.js, and Superface OneSDK on the backend.

You can find the final project on GitHub.

Front-end: Setting up a map with markers

Let’s start by creating an empty React project (using create-react-app):

Open your terminal and navigate to the directory where you want to create your project folder.
Run the following command to create a new React project (Replace <project-name> with the desired name for your project):
```
npx create-react-app <project-name>
```
Navigate into the project folder using the following command:
```
cd <project-name>
```
Open the project in your code editor.
In the src folder, locate the App.js file. This will be the main file where we will make changes for the project. Remove all code in this file.
Optionally remove all unnecessary files, such as test files, default logos etc.
Run the project:
```
npm start
```

Adding the map component

To add a map component, you have many options, like Google Maps or Mapbox, but these are not free. We will use Leaflet, an open-source JavaScript library. With Leaflet, you can easily create interactive maps and add markers, pop-ups, and other types of data visualizations. Leaflet support various providers for map assets, but we will stick with the default, OpenStreetMap.

Leaflet has many official and third party plugins and wrappers. Since we’re using React, we can use React Leaflet which provides components for rendering Leaflet maps in React.

First install leaflet, react-leaflet and leaflet-defaulticon-compatibility. The last package fixes compatibility with Webpack bundler (used by create-react-app) to correctly load images from Leaflet's package.

npm install react-leaflet leaflet leaflet-defaulticon-compatibility

Paste the following code inside App.css file:

/* in src/App.css */

.leaflet-container {
  width: 100vw;
  height: 100vh;
}

And finally, add the following code to App.js file and check if it works:

// src/App.js

import './App.css';

import 'leaflet/dist/leaflet.css';
import 'leaflet-defaulticon-compatibility/dist/leaflet-defaulticon-compatibility.webpack.css';
import { MapContainer, TileLayer } from 'react-leaflet';
import 'leaflet-defaulticon-compatibility';

function App() {
  return (
    <div className="App">
      <MapContainer center={[51.505, -0.09]} id="mapId" zoom={13}>
        <TileLayer url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png" />
      </MapContainer>
    </div>
  );
}

export default App;

If you setup Leaflet correctly, you should see just a map on your page. ![Screenshot of website with map and zoom controls.](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/3v6g5o3xdggkdkvtkhzr.png)

Adding markers on a map

To pinpoint locations on the map, we can use the Marker and Popup components from React Leaflet. The Marker component allows you to add a marker (pin) to a specific location on the map, while the Popup component displays additional information when the marker is clicked or tapped.

Add the following code in App.js:

// src/App.js

import './App.css';

import 'leaflet/dist/leaflet.css';
import 'leaflet-defaulticon-compatibility/dist/leaflet-defaulticon-compatibility.webpack.css';
import { MapContainer, TileLayer, Marker, Popup } from 'react-leaflet';
import 'leaflet-defaulticon-compatibility';

function App() {
  const position = [51.505, -0.09];
  return (
    <div className="App">
      <MapContainer center={[51.505, -0.09]} id="mapId" zoom={13}>
        <Marker position={position}>
          <Popup>Hello World</Popup>
        </Marker>
        <TileLayer url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png" />
      </MapContainer>
    </div>
  );
}

export default App;

Our map should have a marker and a message will show when we click on it. ![Screenshot of website with a map and a marker in the middle with a pop-up with text “Hello World”.](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/iw17ylla4hrp2wq9uekn.png)

Back-end: Pinpointing location entered by the user

Now that we understand how to add markers, we can start by pinpointing an address entered by the user. This will involve using a geocoding API to convert the address into a set of coordinates, which can then be used to place a marker on the map.

We will set up a backend API for the map using Node.js and Express. Once a user enters an address, it is translated to location coordinates using a geocoding API – this part will be handled by Superface. We will use the returned coordinates to place the marker on a map.

Setting up the server project

Within the project folder, create a new folder named server to store the server-side code with empty package.json file.

mkdir server
cd server
npm init -y

Next, install Express.js to handle server-side requests.

# in server/ folder
npm install express

Finally, create an empty server.js file in this folder.

Implementing geocoding with OneSDK

I've decided to use Superface to handle API integration because it makes the process incredibly simple. With Superface, I don't have to deal with the hassle of API documentation and I can use multiple providers with the same interface. Additionally, the Superface catalog offers many ready-made API use cases, making it a valuable tool to have in your toolkit.

Start by installing Superface OneSDK into your server app:

# in server/ folder
npm i @superfaceai/one-sdk

Then implement a use case. We are going to use Geocoding use case with Nominatim provider. But you can, of course, use a different provider. Copy the example code into your server.js file and make a few changes, so we can send the information we will receive from the user:

// server/server.js

const { SuperfaceClient } = require('@superfaceai/one-sdk');
const sdk = new SuperfaceClient();
async function run(loc) {
  // Load the profile
  const profile = await sdk.getProfile('address/geocoding@3.1.2');

  // Use the profile
  const result = await profile.getUseCase('Geocode').perform(
    {
      query: loc,
    },
    {
      provider: 'nominatim',
    }
  );

  // Handle the result
  try {
    const data = result.unwrap();
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

run('Taj Mahal');

Run this function and the coordinates will be returned:

# in server/ folder
$ node server.js
{ latitude: '27.1750123', longitude: '78.04209683661315' }

Adding location search

The initial step is to create an input field for the user to enter a location. Upon submission, we will send the location data via a fetch request and use it to determine the coordinates of that location.

Additionally, I am going to use Font Awesome to add icons to our project. This will make it visually appealing and add to its overall design:

cd .. # Go back from server to the main directory with React project
npm install @fortawesome/fontawesome-svg-core @fortawesome/free-solid-svg-icons @fortawesome/free-regular-svg-icons @fortawesome/react-fontawesome@latest

Now we can use the icons in our project. Paste the following code into App.js file:

// src/App.js

import './App.css';
import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
import { faLocationDot } from '@fortawesome/free-solid-svg-icons';

import 'leaflet/dist/leaflet.css';
import 'leaflet-defaulticon-compatibility/dist/leaflet-defaulticon-compatibility.webpack.css';
import { MapContainer, TileLayer, Marker, Popup } from 'react-leaflet';
import 'leaflet-defaulticon-compatibility';

function App() {
  const position = [51.505, -0.09];

  return (
    <div className="App">
      <form className="inputBlock">
        <input
          type="text"
          id="location"
          name="location"
          required
          placeholder="Enter location"
        />
        <button type="submit" className="addloc">
          <FontAwesomeIcon icon={faLocationDot} style={{ color: '#1EE2C7' }} />
        </button>
      </form>
      <MapContainer center={[51.505, -0.09]} id="mapId" zoom={13}>
        <Marker position={position}>
          <Popup>Hello World</Popup>
        </Marker>
        <TileLayer url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png" />
      </MapContainer>
    </div>
  );
}

export default App;

Paste the CSS code below into App.css:

/* add to src/App.css */

/* Location form */
.inputBlock {
  display: flex;
  justify-content: space-between;
  position: absolute;
  right: 2vw;
  bottom: 2vh;
  padding: 10px;
  z-index: 500;
}

.addloc {
  padding: 5px;
}

.inputBlock input {
  border: 2px solid rgb(41, 38, 38);
  font-size: 1.2rem;
}

.inputBlock button {
  background-color: #282c34;
  font-size: 1.5rem;
  border: 2px black solid;
}

The map should now include a search box in the bottom right corner. ![Screenshot of map with a search box in the bottom right corner](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/lc022x3grzu9vs4ocsof.png)

To preserve the entered location and display it on the map as a pinpoint, we need to retrieve its coordinates using the fetch function and store them using the useState hook.

Paste the following code into App.js file:

// src/App.js

import './App.css';
import { useState } from 'react';
import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
import { faLocationDot } from '@fortawesome/free-solid-svg-icons';

import 'leaflet/dist/leaflet.css';
import 'leaflet-defaulticon-compatibility/dist/leaflet-defaulticon-compatibility.webpack.css';
import { MapContainer, TileLayer, Marker, Popup } from 'react-leaflet';
import 'leaflet-defaulticon-compatibility';

function App() {
  const [locationMarkers, setLocationMarkers] = useState([]);

  async function handleMarkerSubmit(event) {
    event.preventDefault();
    const formData = new FormData(event.target);
    const inputLocation = formData.get('location');

    const res = await fetch(
      '/api/geocode?' +
        new URLSearchParams({ location: inputLocation }).toString()
    );
    if (!res.ok) {
      const err = await res.text();
      alert(`Something went wrong.\n${err}`);
    } else {
      const data = await res.json();
      let newLocation = {
        address: data.location,
        lat: data.coordinates.latitude,
        long: data.coordinates.longitude,
      };
      setLocationMarkers((locations) => [...locations, newLocation]);
    }
  }

  return (
    <div className="App">
      <form className="inputBlock" onSubmit={handleMarkerSubmit}>
        <input
          type="text"
          id="location"
          name="location"
          required
          placeholder="Enter location"
        />
        <button type="submit" className="addloc">
          <FontAwesomeIcon icon={faLocationDot} style={{ color: '#1EE2C7' }} />
        </button>
      </form>
      <MapContainer center={[51.505, -0.09]} id="mapId" zoom={13}>
        {locationMarkers.map((loc, key) => {
          return (
            <Marker key={key} position={[loc.lat, loc.long]}>
              <Popup>{loc.address}</Popup>
            </Marker>
          );
        })}
        <TileLayer url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png" />
      </MapContainer>
    </div>
  );
}

export default App;

And the following code into server.js :

// server/server.js

const express = require('express');
const app = express();
const { SuperfaceClient } = require('@superfaceai/one-sdk');
const sdk = new SuperfaceClient();
const PORT = 5000;
app.use(express.json());

async function geocodeLocation(loc) {
  // Load the profile
  const profile = await sdk.getProfile('address/geocoding@3.1.2');

  // Use the profile
  const result = await profile.getUseCase('Geocode').perform(
    {
      query: loc,
    },
    {
      provider: 'nominatim',
    }
  );

  // Handle the result
  const data = result.unwrap();
  return data;
}

app.get('/api/geocode', async (req, res) => {
  try {
    const location = req.query.location;
    const coordinates = await geocodeLocation(location);
    res.json({ location, coordinates });
  } catch (error) {
    res.status(500).json(error);
  }
});

app.listen(PORT, () => {
  console.log(`Server listening on ${PORT}`);
});

Now we will need to start the backend server.

cd server/
npm start

To access the backend server from our React application, we can use requests proxying in Create React App. The server runs on port 5000, so we'll add the following line to the top package.json file in our main project:

"proxy": "http://localhost:5000"

You may need to restart create-react-app server. After doing that, you should be able to search for locations and see markers on your app.

Routing between two locations

Setting up Routing Machine

To create routes between two locations with Leaflet, we will use a Routing Plugin. This plugin will enable us to display routes on the map.

There are many plugins that we can use. I will go with Leaflet Routing Machine.

First, install the package:

npm install leaflet-routing-machine@3.2.12

Create a RoutingMachine.js file in src folder and copy and paste the below code. This will allow us to create route between the two different locations we pass to waypoints

// src/RoutingMachine.js

import L from 'leaflet';
import { createControlComponent } from '@react-leaflet/core';
import 'leaflet-routing-machine';
import 'leaflet-routing-machine/dist/leaflet-routing-machine.css';

const createRoutineMachineLayer = ({ waypoints }) => {
  const instance = L.Routing.control({
    waypoints: waypoints.map(({ latitude, longitude }) =>
      L.latLng(latitude, longitude)
    ),
    draggableWaypoints: false,
  });

  return instance;
};

const RoutingMachine = createControlComponent(createRoutineMachineLayer);

export default RoutingMachine;

Then, we will import this RoutingMachine.js component into our App.js file and provide it with the coordinates of two different locations as props.

Copy and paste the following code in App.js file:

// src/App.js

import './App.css';
import { useState, useEffect } from 'react';
import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
import { faLocationDot, faRoute } from '@fortawesome/free-solid-svg-icons';

import 'leaflet/dist/leaflet.css';
import 'leaflet-defaulticon-compatibility/dist/leaflet-defaulticon-compatibility.webpack.css';
import { MapContainer, TileLayer, Marker, Popup } from 'react-leaflet';
import 'leaflet-defaulticon-compatibility';

import RoutingMachine from './RoutingMachine';

function App() {
  const [locationMarkers, setLocationMarkers] = useState([]);
  const waypoints = [
    {
      latitude: 51.505,
      longitude: -0.09,
    },
    {
      latitude: 51.467,
      longitude: -0.458,
    },
  ];

  async function handleMarkerSubmit(event) {
    event.preventDefault();
    const formData = new FormData(event.target);
    const inputLocation = formData.get('location');

    const res = await fetch(
      '/api/geocode?' +
        new URLSearchParams({ location: inputLocation }).toString()
    );
    if (!res.ok) {
      const err = await res.text();
      alert(`Something went wrong.\n${err}`);
    } else {
      const data = await res.json();
      let newLocation = {
        address: data.location,
        lat: data.coordinates.latitude,
        long: data.coordinates.longitude,
      };
      setLocationMarkers((locations) => [...locations, newLocation]);
    }
  }

  return (
    <div className="App">
      <form className="inputBlock" onSubmit={handleMarkerSubmit}>
        <input
          type="text"
          id="location"
          name="location"
          required
          placeholder="Enter location"
        />
        <button type="submit" className="addloc">
          <FontAwesomeIcon icon={faLocationDot} style={{ color: '#1EE2C7' }} />
        </button>
      </form>
      <MapContainer center={[51.505, -0.09]} id="mapId" zoom={13}>
        {locationMarkers.map((loc, key) => {
          return (
            <Marker key={key} position={[loc.lat, loc.long]}>
              <Popup>{loc.address}</Popup>
            </Marker>
          );
        })}
        <TileLayer url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png" />
        {waypoints ? <RoutingMachine waypoints={waypoints} /> : ''}
      </MapContainer>
    </div>
  );
}

export default App;

With Routing Machine added, you should see a route between two static waypoints. ![Screenshot of map with two markers and a red route between them, with navigation instructions in top right corner.](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/1bijg5ifszek60ugr78o.png)

Routing inputs

We will add input fields for the user to enter two distinct locations, the starting point and the final destination. Then we will ask for coordinates from the server using fetch and pass them as properties to the RoutingMachine.js component. We will also create another route in the server.js file to handle requests for calculating the route between the two locations.

Copy and paste the code in App.js:

// src/App.js

import './App.css';
import { useState, useEffect } from 'react';
import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
import { faLocationDot, faRoute } from '@fortawesome/free-solid-svg-icons';

import 'leaflet/dist/leaflet.css';
import 'leaflet-defaulticon-compatibility/dist/leaflet-defaulticon-compatibility.webpack.css';
import { MapContainer, TileLayer, Marker, Popup } from 'react-leaflet';
import 'leaflet-defaulticon-compatibility';

import RoutingMachine from './RoutingMachine';

function App() {
  const [locationMarkers, setLocationMarkers] = useState([]);
  const [waypoints, setWaypoints] = useState();
  const [showRoutingForm, setFormView] = useState(false);

  useEffect(() => {}, [waypoints]);

  async function handleMarkerSubmit(event) {
    event.preventDefault();
    const formData = new FormData(event.target);
    const inputLocation = formData.get('location');

    const res = await fetch(
      '/api/geocode?' +
        new URLSearchParams({ location: inputLocation }).toString()
    );
    if (!res.ok) {
      const err = await res.text();
      alert(`Something went wrong.\n${err}`);
    } else {
      const data = await res.json();
      let newLocation = {
        address: data.location,
        lat: data.coordinates.latitude,
        long: data.coordinates.longitude,
      };
      setLocationMarkers((locations) => [...locations, newLocation]);
    }
  }

  async function handleRouteSubmit(event) {
    event.preventDefault();
    // Reset previous waypoints
    if (waypoints) {
      setWaypoints();
    }
    // Hide the form
    setFormView(false);

    const formData = new FormData(event.target);
    const locations = formData.getAll('location');
    const res = await fetch('/api/route', {
      method: 'POST',
      headers: {
        Accept: 'application/json',
        'Content-Type': 'application/json;charset=UTF-8',
      },
      body: JSON.stringify({ locations }),
    });
    if (!res.ok) {
      const err = await res.text();
      alert(`Something went wrong.\n${err}`);
    } else {
      const data = await res.json();
      setWaypoints(data.waypoints);
    }
  }

  return (
    <div className="App">
      <form className="inputBlock" onSubmit={handleMarkerSubmit}>
        <input
          type="text"
          id="location"
          name="location"
          required
          placeholder="Enter location"
        />
        <button type="submit" className="addloc">
          <FontAwesomeIcon icon={faLocationDot} style={{ color: '#1EE2C7' }} />
        </button>
      </form>
      <div className="routeBlock">
        <div className="addRoutes">
          {showRoutingForm && (
            <form onSubmit={handleRouteSubmit}>
              <div className="posOne">
                <input
                  type="text"
                  name="location"
                  required
                  placeholder="Staring Point"
                />
              </div>
              <div className="posTwo">
                <input
                  type="text"
                  name="location"
                  required
                  placeholder="End Point"
                />
              </div>
              <button className="addloc">Find Path</button>
            </form>
          )}
          <FontAwesomeIcon
            icon={faRoute}
            style={{ color: '#1EE2C7' }}
            onClick={() => {
              setFormView((showRoutingForm) => !showRoutingForm);
            }}
          />
        </div>
      </div>
      <MapContainer center={[31.505, 70.09]} id="mapId" zoom={4}>
        {locationMarkers.map((loc, key) => {
          return (
            <Marker key={key} position={[loc.lat, loc.long]}>
              <Popup>{loc.address}</Popup>
            </Marker>
          );
        })}
        <TileLayer url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png" />
        {waypoints ? <RoutingMachine waypoints={waypoints} /> : ''}
      </MapContainer>
    </div>
  );
}

export default App;

Add the below CSS code in App.css:

/* add to src/App.css */
/* Routing form */
.routeBlock {
  position: absolute;
  left: 0.5vw;
  bottom: 2vh;
  z-index: 500;
  padding: 5px;
  font-size: 2rem;
  border: 2px solid rgb(41, 38, 38);
  background-color: #282c34;
}

.routeBlock input {
  font-size: 1rem;
}

And here’s the final version of server.js file:

// server/server.js

const express = require('express');
const app = express();
const { SuperfaceClient } = require('@superfaceai/one-sdk');
const sdk = new SuperfaceClient();
const PORT = 5000;
app.use(express.json());

async function geocodeLocation(loc) {
  // Load the profile
  const profile = await sdk.getProfile('address/geocoding@3.1.2');

  // Use the profile
  const result = await profile.getUseCase('Geocode').perform(
    {
      query: loc,
    },
    {
      provider: 'nominatim',
    }
  );

  // Handle the result
  const data = result.unwrap();
  return data;
}

app.get('/api/geocode', async (req, res) => {
  try {
    const location = req.query.location;
    const coordinates = await geocodeLocation(location);
    res.json({ location, coordinates });
  } catch (error) {
    res.status(500).json(error);
  }
});

app.post('/api/route', async (req, res) => {
  try {
    const locations = req.body.locations;
    if (locations.length !== 2) {
      res.status(422).json({ error: 'Expected 2 waypoints' });
      return;
    }
    const waypoints = await Promise.all(
      locations.map((location) => geocodeLocation(location))
    );
    res.json({ waypoints });
  } catch (error) {
    res.status(500).json(error);
  }
});

app.listen(PORT, () => {
  console.log(`Server listening on ${PORT}`);
});

Final file structure

google-maps-clone
├── package.json
├── package-lock.json
├── public
│   └── index.html
├── README.md
├── server
│   ├── package.json
│   ├── package-lock.json
│   └── server.js
└── src
    ├── App.css
    ├── App.js
    ├── index.css
    ├── index.js
    └── RoutingMachine.js

Conclusion

In this tutorial, we have learned how to create a Google Maps-like application using Leaflet and React. We've utilized Geolocation API to identify location coordinates and place markers, as well as creating a route between two different locations. You can find the final project on GitHub.

superfaceai / google-maps-clone

Let's build a basic Google Maps clone! Complementary code to the tutorial.

Google Maps clone with React, Leaflet, and OneSDK

A complementary code to the tutorial Let's build a Google Maps clone.

Provides the following features:

Displaying a map
Adding markers to the map using location search
Display route and routing instructions between two places

Uses the following libraries:

React with Create React App
Leaflet
- React Leaflet
- Leaflet Routing Machine
- leaflet-defaulticon-compatibility to fix icons bundling in Create React App
Express for backend
OneSDK with Geocoding use case

Uses the following providers:

OpenStreetMap map tiles
Nominatim for geocoding (via OneSDK)
OSRM for routing (via Leaflet Routing Machine)

Warning The choice of providers is for low volume, development purposes only. Leaflet Routing Machine recommends different routing provider for production. For geocoding, various other providers are supported.

Setup

Clone the repository

git clone https://github.com/superfaceai/google-maps-clone.git

Install dependencies for both the frontend and backend

cd google-maps-clone
npm install
cd server
npm install
cd ..

Usage

…

View on GitHub

There are many more features that can be added to enhance this map project. For example real-time tracking of the user's location, integrating voice assistance for routing, using IP geolocation API, customizing marker icons, and much more.

Check out more geocoding integrations

If you have suggestions on what features to add, or if you'd like to show how you've used this tutorial, leave a comment or come tell us on our Discord. Don't be shy!

Get started with Greenhouse APIs: Overview and authentication

Jan Vlnas — Thu, 11 May 2023 12:12:08 +0000

Our goal at Superface is to simplify API integrations, so you can focus on building your app instead of reading the API docs. We’ve built ready-made integrations for Greenhouse, and in this article we’re sharing what we’ve learned through the process.

The first step to integrating any API is obtaining access. When it comes to Applicant Tracking Systems (ATS), the API for Greenhouse is among the most developer-friendly, with useful and straightforward documentation.

Still, there are six separate APIs for Greenhouse, some of them with overlapping concerns (such as Harvest and Job Board APIs). We have prepared a little crash course on Greenhouse APIs with pointers on when to use which one, how to obtain credentials for each, and how to authenticate your API calls. You will also find examples in JavaScript, which should work in all modern runtimes (particularly Node.js version 18 and newer and Deno).

This article focuses on Greenhouse Recruiting APIs. There are also APIs for Greenhouse Onboarding and Assessment. We will cover these in future posts.

Summary

The Job Board API is intended for building custom careers pages.
- It’s publicly accessible without authentication, cached and not rate limited.
- It only uses HTTP Basic authentication for submitting candidates through the API.
The Harvest API provides full access to Greenhouse Recruiting data.
- It’s useful for building advanced automation and internal productivity tools.
- It requires HTTP Basic authentication using API keys with granular permissions, and an On-Behalf-Of header for auditing of write operations.
- The number of requests is limited within 10-second windows.
The Candidate Ingestion API is intended for recruiting partners, like agencies and job portals.
- Access is authenticated either with HTTP Basic authentication (with API key provided by Greenhouse customer), or OAuth 2.0 with granular scopes.
- Requests authenticated by HTTP Basic require an On-Behalf-Of header, which identifies the Greenhouse user and sets the integration’s permissions.

Job Board API for custom careers pages

You can use the Job Board API to build a custom careers page for your company. It provides data about published jobs and the company hierarchy (offices and departments). Since job boards only work with published and public data, you don’t need any special credentials for read access – only a “board token” which corresponds to the URL path of a job board (and can be customized).

For example, if the job board is accessible on the URL https://boards.greenhouse.io/acme, the board_token is acme. Anyone can access the respective API endpoints, for example https://boards-api.greenhouse.io/v1/boards/acme/jobs to list published jobs.

The only exception is posting job applications, which requires an API key. Greenhouse recommends using their embedded application form, but if you decide to build one on your own, you will need to create a Job Board API key, which you’ll use in HTTP Basic authentication as the username, with no password. For example, in JavaScript with Node.js (v18+) or Deno, you can submit an application as follows:

// Set according to your Job Board settings
const JOB_BOARD_TOKEN = `acmeinc`;
// Create Job Board key in Configure > Dev Center > API Credentials
const GREENHOUSE_API_KEY = `2f11da80ea73b20b4d15bfab0ee73257-1`;
// ID of the job where the application is submitted
const JOB_ID = '4043584006';

const CANDIDATE_DATA = {
  first_name: 'Jane',
  last_name: 'Doe',
  email: 'j.doe@example.com',
  phone: '12345678',
  data_compliance: {
    gdpr_consent_given: true,
  },
};

// base64 encode credentials
const basicAuth = btoa(`${GREENHOUSE_API_KEY}:`);

fetch(
  `https://boards-api.greenhouse.io/v1/boards/${JOB_BOARD_TOKEN}/jobs/${JOB_ID}`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Basic ${basicAuth}`,
    },
    body: JSON.stringify(CANDIDATE_DATA),
  }
)
  .then((response) => {
    if (response.ok) {
      return response.json();
    } else {
      throw new Error(
        `Unexpected response from the server: ${response.status}`
      );
    }
  })
  .then((responseData) => {
    console.log('Application submitted!', responseData);
  })
  .catch((error) => {
    console.error('Error submitting application:', error);
  });

Harvest API for full access to recruiting data

A step above the public Job Board API is the Harvest API, which provides access to “most” Greenhouse Recruiting data. This API gives you full access to read and modify candidates, interviews, jobs, and various other organization’s resources.

Harvest API keys have granular permissions. You can choose what API endpoints and operations are available, so you can limit the access scope (and potential security risks) of your application.

Similarly to the Job Board API, Harvest API keys are used with HTTP Basic authentication, where the username is the API key and the password remains empty.

In the following JavaScript example, we’re listing all candidates from the Harvest API using the GET Candidates endpoint. The pagination is handled through an async iterable. Each API response has a Link header for navigating to the next page of results, so we’re parsing the header in the sample code:

// Create Harvest API key in Configure > Dev Center > API Credentials
const GREENHOUSE_API_KEY = `c8ee19deadbeef5466d92e643916316-2`;

// base64 encode credentials
const basicAuth = btoa(`${GREENHOUSE_API_KEY}:`);

// Parse Link header:
// Example: <https://harvest.greenhouse.io/v1/candidates?page=2&per_page=2>; rel="next", <https://harvest.greenhouse.io/v1/candidates?page=474&per_page=2>; rel="last"
function getNextPageUrl(linkHeader) {
  if (!linkHeader) {
    return '';
  }
  const links = linkHeader.split(',');
  const nextLink = links.find((link) => link.includes('rel="next"'));
  if (!nextLink) {
    return '';
  }
  const nextUrl = nextLink.match(/<(.+)>/)[1];
  return nextUrl;
}

async function* fetchCandidatesPage() {
  // TIP: add ?per_page=1 to test iteration or ?per_page=500 to get a maximum of results
  let nextPageUrl = 'https://harvest.greenhouse.io/v1/candidates';

  while (nextPageUrl) {
    const response = await fetch(nextPageUrl, {
      headers: {
        Authorization: `Basic ${basicAuth}`,
      },
    });
    if (response.ok) {
      nextPageUrl = getNextPageUrl(response.headers.get('Link'));
      const data = await response.json();
      yield data;
      console.log(nextPageUrl);
    } else {
      throw new Error(
        'Unexpected response from the server: ',
        await response.text()
      );
    }
  }
}

async function iterateCandidates() {
  let page = 0;
  for await (const candidates of fetchCandidatesPage()) {
    console.log(`### Listing candidates, page ${page}`);
    console.log(candidates);
    page++;
  }
}

iterateCandidates();

Since the API key is global, there is no straightforward way to identify who performed which operations through the API. Therefore, for auditing purposes, write operations (creating, updating, and deleting resources) require an On-Behalf-Of HTTP header containing the Greenhouse ID of the user performing the operation. Your application can get the ID of the user from the GET List Users endpoint. If you know the email of the user logged into your app, you can use the email query parameter to obtain the user’s Greenhouse record, including their ID.

Job Board API vs. Harvest API

The Job Board API is clearly a subset of the Harvest API, so you may be asking why should you deal with the Job Board API at all?

This depends on the type of application you’re building. The Job Boards API is mostly useful for custom career sites, so if you’re building that, consider the following advantages:

Security: Since the Job Board API is limited only to public data such as published job posts, there’s no risk of leaking sensitive information (for example if the API key is compromised).
Rate Limits: The Job Board API is heavily cached and there are no hard rate limits, while requests to the Harvest API are throttled within a 10-second window.
Simplicity: Since the Job Board API is publicly accessible, you can use it with purely client-side applications. For the Harvest API, you will need to implement a backend to keep the API key secure and to filter out internal data.

On the other hand, the Job Board API doesn’t expose some data, which may be helpful for building custom integrations. Particularly lacking are external IDs of offices and departments (useful for mapping office or department descriptions to an external CMS), or the time when a job was first published (for displaying jobs which were recently added, not updated).

Candidate Ingestion API for sourcing partners

The Candidate Ingestion API is intended for sourcing partners, like external job portals and agencies. It provides limited access to jobs and candidates, as well as the ability to post new candidates.

Similarly to the Harvest API, the Candidate Ingestion API requires HTTP Basic authentication with the API key as the username, an empty password, and the On-Behalf-Of header. However, the On-Behalf-Of must be set to the user’s e-mail. The permissions of the integration are limited to the user’s role. Typically, you will have a dedicated “service account” for the integration.

In this JavaScript sample, we’re listing jobs using the Candidate Ingestion API

// Create Candidate Ingestion API key in Configure > Dev Center > API Credentials; in Partners, select Resource (dev)
const GREENHOUSE_API_KEY = `321a2ff8cdcdeadbeefd372a9c1a69e9-3`;
// Your email or for a dedicated service account
const ON_BEHALF_OF = 'demo@example.com';

// base64 encode credentials
const basicAuth = btoa(`${GREENHOUSE_API_KEY}:`);

fetch(`https://api.greenhouse.io/v1/partner/jobs`, {
  headers: {
    Authorization: `Basic ${basicAuth}`,
    'On-Behalf-Of': ON_BEHALF_OF,
  },
})
  .then((response) => {
    if (response.ok) {
      return response.json();
    } else {
      throw new Error(
        `Unexpected response from the server: ${response.status}`
      );
    }
  })
  .then((responseData) => {
    console.log(responseData);
  })
  .catch((error) => {
    console.error(error);
  });

The Candidate Ingestion API also provides OAuth 2.0 authorization, with granular scopes for viewing jobs, candidates, and creating candidates. Consumer key and secret are provided by Greenhouse. The access token is bound to the user who authorized the application, and therefore the On-Behalf-Of header is not needed.

Time to build the integration

Picking an API and getting the right API key is just the start. Now you’ll need to read the documentation, figure out the resources, properties, API calls… And once you build the integration, you also need to keep checking the API for changes and breakages.

Maybe there’s a better way. We've already went through multiple ATSs and distilled their APIs into ready-made ATS connectors, so you don’t need to read the docs and can focus on building your app instead.

With Superface, you’ll get unified integration logic which shields your application from API changes, and provides enhanced monitoring. Our SDK provides direct, proxy-less integration with the external API, so it’s faster and respects the privacy of your candidates. And you’re not reliant on our ready-made connectors – you can modify the integration logic to suit your needs, and build your own connectors.

If that sounds interesting, take a look at our Greenhouse ATS integrations – but we also provide other integrations, like geolocation, sending emails, Slack, and more. In case you have any questions or troubles with Greenhouse (or any other) API, meet us on our Discord server.

We’re posting more tutorials for APIs regularly. To stay in touch, subscribe to our newsletter or follow us here on DEV, LinkedIn, or Twitter.

Twitter API Changes: The missing FAQ for Free & Basic access

Jan Vlnas — Fri, 07 Apr 2023 08:11:22 +0000

Last week, the new Twitter API access tiers were finally announced. Unfortunately, some important details were left out from the announcement, leaving many developers confused and stressed out as the deprecation deadline is getting closer.

At Superface, we maintain social media integrations, including Twitter’s, and we’ve built an authorization library for Twitter API, so we’ve been closely observing the recent developments around Twitter API. (I’ve even made a site for that.)

In this article, I have collected observations and recommendations about Twitter’s new API. In summary:

If possible, don’t migrate to the new plans yet
You can use Twitter Login for free both with OAuth 2.0 and OAuth 1.0a
You need to migrate your app to API v2
You can post tweets with media
You can still embed tweets
If you need to do anything else than login users or post tweets, you'll have to pay a monthly fee (maybe even a large sum)
Don’t rely on official support

Here’s a warning, though: Twitter is in constant flux, so any information in this article can become outdated at any time. I will do my best to keep it up to date – check the changelog and the original article for updates. If you notice any false or outdated information, please let me know.

What do we know from the announcement?

The changes were announced on the Twitter Dev account and the community forums. Here's what we can learn from these announcements:

All existing API access tiers (Standard, Premium, Essential, and Elevated) are being replaced by the new Free and Basic tiers.
Both tiers allow users to log in with Twitter, read the profile of an authorized user, and post tweets on behalf of users.
Only the paid Basic tier provides read access to user profiles and tweets at a much lower rate than previous tiers (10,000 tweets per month, compared to 500,000 on Essential and 2 million on Elevated).
The Basic tier costs $100 / month.
The v1.1 API is being deprecated in favor of the v2 API (with an exception for media uploads, see below).
The previous plans and legacy API will be deprecated by April 29th, 2023 at the latest – so technically the changes can happen any time sooner.
The Twitter Ads API is unaffected by these changes.
There are no special access plans for researchers and academics at this time.

Do I need to pay so the users of my app can log in with Twitter?

No, Twitter Login is available on the Free plan.

You can also read the information about a logged-in user through the GET /2/users/me endpoint. It is rate limited to 25 requests per 24 hours per user, so just make sure your integration code doesn’t read this endpoint too frequently (or fails gracefully when you hit the limit).

During my testing, I also frequently encountered a “Something went wrong” error on Twitter’s authorization page.

After a few retries, the authorization flow was successful. If your users encounter a similar issue, instruct them to just retry logging in a few times.

Do I need to use OAuth 2.0 for login?

No, both OAuth 1.0a and OAuth 2.0 (with app-only and user contexts) are supported on both access tiers.

You must use OAuth 1.0a if you want to publish tweets with images or videos. On the other hand, newer API features, like Bookmarks or Spaces are available only with OAuth 2.0. Check the Twitter v2 Authentication Mapping to see what features are supported in respective authentication contexts.

Do I need to migrate to the Twitter API v2?

Yes. According to the announcement, both Standard v1.1 and Premium v1.1 endpoints will be deprecated. The Basic tier is described as:

Rate limited access to suite of v2 endpoints

The only exceptions are media upload endpoints, which are not available in the v2 API.

Can I post tweets with media (images, GIFs, videos)?

Yes, that’s possible even on the Free plan, but you need to combine v2 API endpoints with v1.1 media upload endpoints. You must use OAuth 1.0a with read+write access, as media upload endpoints don’t support OAuth 2.0 access tokens.

Follow these steps to post a tweet with media attachments:

Upload media using the Upload media endpoints: POST media/upload for images or chunked upload endpoints for videos.
You will receive media_id for the uploaded objects.
Post a tweet using the POST /2/tweets endpoint and reference the uploaded media objects in a media property like this:

   {
     "text": "Tweet with media",
     "media": { "media_ids": ["1455952740635586573"] }
   }

Can I only post tweets with Free access?

Mostly, yes. It’s possible only to manage a user’s tweets (i.e., create, delete), upload media, and look up information about the authorized user.

If you hit a paid endpoint, you will get a non-descriptive error message like this:

{
  "title": "Forbidden",
  "type": "about:blank",
  "status": 403,
  "detail": "Forbidden"
}

Notably, you can’t read user’s tweets timeline or the mentions timeline. So if you are building an application that tracks users’ mentions (e.g., social media care or analytics, or a bot that replies to tweets), you will have to pay for Basic access.

I need to read more than 10,000 tweets per month, what should I do?

The next access tier after the Basic is Enterprise, which, according to the leaked sales documents, starts at $42,000 per month. You can apply through the Twitter Developer Portal.

No doubt there are other ways to get the data for cheaper or for free, but that’s outside the scope of this article.

Can I embed tweets?

Yes, Twitter for Websites features remain unaffected by these changes, including Embedded Tweets.

While there are reports of broken embeds, they are usually caused by suspended access to the Twitter API. For example, Substack reported issues with embeds, however, they use custom embeds unrelated to the official widgets. If you embed tweets on your own by fetching them from API, you will need to pay at least for the basic plan.

Should I migrate to the new plans now?

No. If you currently have Essential or Elevated access, I recommend stalling the migration to the Free and Basic plans at least until the limits enforcement stabilizes a bit. On the community forums, some users report losing access after purchasing the Basic access, probably because they were over the 10,000 tweets/month limit at the time of the purchase. Other users report issues with rate limits. These bugs seem to be symptoms of rushed development. We can hope that they will be fixed before the April 29th deadline.

Consider setting up a separate developer account with either Free or Basic access and test your application there first, before migrating your main account.

If you're using API v1.1, you should migrate your application to API v2. The new API is accessible both on the Essential and Elevated plans. Check Twitter’s migration guides.

And of course, be prepared that Twitter can suspend your application at any time, migrated or not.

Where can I get help with Twitter API?

If you run into issues with migration to the new access plans, don’t expect any help or refund from Twitter. As Ryan Barrett on the Twitter Developers forum points out, you can treat the Twitter API as effectively unmaintained.

Still, the Twitter Developers forum is probably the best place where you can get help from community volunteers and a good place to search for known issues.

If you’re migrating a Node.js application to API v2, take a look at our ready-made social media integrations, and our Twitter OAuth 2.0 strategy for Passport.js. We'll be happy to help you with Twitter API on Superface Discord or you can reach directly to us.

Your article is wrong or outdated / I still have questions

Please – let me know! Leave a comment or reach out to me on Mastodon or Discord.

I’m also sending out a monthly Superface Newsletter, so if you’d like to stay in touch and get more articles like this one with a mix of API and AI news, feel free to subscribe.

Turn CV to structured data with GPT-3 and Node.js

Jan Halama — Tue, 24 Jan 2023 13:49:50 +0000

Large language models like GPT-3 are useful to simplify routine tasks. For example, we can take unstructured data, like a job applicant's resume in PDF, and turn them into structured data and fill them into our Applicant Tracking System (ATS) like Greenhouse or Workable.

In this article, I will show you a Node.js application which does that. But while GPT-3 simplifies routine data entry jobs, as developers we still need to connect all the respective APIs to download the applicant's CV, get text from the PDF, and put data to the ATS. Luckily, Superface gets us rid of this routine API wiring. We provide a unified interface across many API providers. Switching from, for example, Workable to Breezy HR, is a one line change.

Let's check what steps this application does:

Loads a CV of a candidate who applied for a given job from an Applicant Tracking System (ATS), like Workable or Greenhouse.
Converts the CV to text and parses the text into machine-readable data.
Updates the candidate in the ATS with the data obtained from the CV.

You can find the complete application in the CV Analyzer repository. It uses the following packages:

@superfaceai/one-sdk - Superface OneSDK is used to integrate with ATS, OpenAI and Cloudmersive SaaS providers.
node-fetch - NodeFetch is used to fetch the CV document.
dotenv - dotenv is used to load environment variables.
inquirer - Inquirer.js is used to build interactive user interface.

We also rely on these use cases from Superface Catalog:

In this demo we use Workable as ATS, Cloudmersive to convert a candidate's CV to plain text, and OpenAI provider for conversion of CV to structured data. But you are not limited to just this three providers. For ATS use cases you can use also Breezy HR, Greenhouse and many others.

Setting up the application

1. Clone the app repository and enter its directory.

git clone git@github.com:superfaceai/cv-analyzer.git
cd cv-analyzer

2. Install dependencies.

npm install

3. Create accounts (if you do not have them already) for the providers:

Workable offers 15 days free trial. A work e-mail address is required to create the account.
Cloudmersive has a free tier limited to 800 requests per month.
OpenAI offers a free trial with $18 in free credit usable during the first 3 months.

4. Copy the example .env file.

cp .env.example .env

5. Set credentials and integration parameters for the providers in the .env file.

Get Workable Access Token and Subdomain.
Create Cloudmersive Free Tier Key.
Create OpenAI Secret API Key.

6. Create a job position and add new candidate in Workable ATS.

7. Start the app.

npm start

Once the application starts, it will show you a list of candidates. When you pick one, it will update candidate's entry with data parsed from their CV.

How the application works

The main flow of the application is in the src/index.js file, which calls use cases defined in src/use_cases.js file.

Selecting the candidate and getting its CV

First we list open job positions and candidates for the selected position. This is handled with the List Jobs use case; once the user picks a job position, we use List Candidates use case with the respective ID of the job position:

exports.listCandidates = async (sdk, providerOptions, jobId) => {
  const listCandidatesProfile = await sdk.getProfile(
    'recruitment/list-candidates@1.0.0'
  );
  const listCandidatesResult = await listCandidatesProfile
    .getUseCase('ListCandidates')
    .perform(
      {
        jobId,
      },
      providerOptions
    );
  return listCandidatesResult.unwrap().candidates;
};

We take the ID of the selected candidate and use the Get CV use case to obtain the URL of a document with the candidate's resume (typically that's a PDF, but the ATS may accept other formats as well):

exports.getCVUrl = async (sdk, providerOptions, candidateId) => {
  const getCVProfile = await sdk.getProfile('recruitment/get-cv@1.0.0');
  const getCVResult = await getCVProfile.getUseCase('GetCV').perform(
    {
      candidateId,
    },
    providerOptions
  );
  return getCVResult.unwrap().cv.documentUrl;
};

Converting CV to text

Now we know where the candidate's CV can be downloaded, but we need to extract the text from it somehow. We use Convert Document to Text use case for that – we fetch the document and upload it to the conversion provider (Cloudmersive in this example) and get a plain text in return.

exports.convertCVToText = async (sdk, providerOptions, cvDocumentUrl) => {
  const docToTextProfile = await sdk.getProfile(
    'file-conversion/doc-to-text@1.0.0'
  );

  const fetchDocumentResponse = await fetch(cvDocumentUrl);

  if (!fetchDocumentResponse.body) {
    console.error('Failed to fetch CV document.');
    return;
  }

  const result = await docToTextProfile
    .getUseCase('ConvertDocumentToText')
    .perform(
      {
        fileName: 'cv.pdf',
        content: BinaryData.fromStream(fetchDocumentResponse.body),
      },
      providerOptions
    );

  return result.unwrap().text;
};

Extracting structured data

Now it's time for some AI magic! We use OpenAI's GPT-3 model through the Text Completion use case. We provide the model with a prompt explaining we need particular data returned as JSON:

exports.analyzeCV = async (sdk, providerOptions, cvText) => {
  try {
    const generateTextProfile = await sdk.getProfile('ai/generate-text@1.0.0');

    const promptCommand = `Parse following job applicant resume and return json object with properties 
    { 
      "firstName", "lastName", "address", "phone", 
      "education":
      [{"school", "fieldOfStudy", "studiedFrom_ISO8601":"YYYY-MM-DD", "studiedTill_ISO8601":"YYYY-MM-DD"}],
    "workHistory":
      [{"company", "position", "summary", "workedFrom_ISO8601:"YYYY-MM-DD"", "workedTill_ISO8601":"YYYY-MM-DD"}]
    }. `;

    const result = await generateTextProfile.getUseCase('CompleteText').perform(
      {
        prompt: promptCommand + cvText,
        creativity: 0.8,
        approxMaxWords: 1000,
        model: 'large',
      },
      providerOptions
    );

    analyzeCVOutcome = result.unwrap();
  } catch (error) {
    console.error('Failed to analyze CV.', error);
  }
  // ...
};

If the analysis goes well and the model “completes” our prompt, we turn the returned completion to JSON:

const parsedCV = JSON.parse(analyzeCVOutcome.completions[0]);
const mappedCV = {
  ...parsedCV,
  education: parsedCV.education?.map(school => {
    return {
      school: school.school,
      degree: school.degree,
      fieldOfStudy: school.fieldOfStudy,
      startedAt: school.studiedFrom_ISO8601,
      endedAt: school.studiedTill_ISO8601,
    };
  }),
  workHistory: parsedCV.workHistory?.map(work => {
    // ...
  }),
};

return mappedCV;

Update the candidate data

Now that we have a JSON with structured data extracted from the CV, we can send the data back to the ATS to update the candidate's data using the Update Candidate use case:

exports.updateCandidate = async (sdk, providerOptions, candidate) => {
  const profile = await sdk.getProfile('recruitment/update-candidate@1.0.0');

  const result = await profile
    .getUseCase('UpdateCandidate')
    .perform(candidate, providerOptions);

  result.unwrap();

  return true;
};

Using another ATS?

If you take a look at the code, there aren't any mentions of Workable, Cloudmersive or OpenAI. That's because the use cases are designed in provider-neutral way. In case of ATS, we use a unified terminology, so if you need to use another ATS, you don't need to rewrite the whole application. Instead, you can change atsProviderOptions in src/index.js file:

// Options for Workable
const atsProviderOptions = {
  provider: 'workable',
  parameters: {
    SUBDOMAIN: process.env.WORKABLE_SUBDOMAIN,
  },
  security: {
    bearer_token: {
      token: process.env.WORKABLE_TOKEN,
    },
  },
};

And if you'd like to use, for example, Breezy HR, set atsProviderOptions like this:

// Options for Breezy HR
const atsProviderOptions = {
  provider: 'breezy-hr',
  parameters: {
    COMPANY_ID: process.env.BREEZY_HR_COMPANY_ID,
    ACCESS_TOKEN: process.env.BREEZY_HR_ACCESS_TOKEN,
  },
};

Next steps

In this demo application, we've used 6 different API use cases from 3 different API providers, without ever looking at the API docs. That's the advantage of Superface.

Do you need to integrate Applicant Tracking Systems like Workable, Lever, or SAP SuccessFactors? Check out our Applicant Tracking Systems integrations. And don't miss other integrations in the Superface catalog.

Instagram Graph API Explained: How to log in users

Jan Vlnas — Tue, 03 Jan 2023 13:16:21 +0000

There are two ways how to access the Instagram API:

Through Instagram’s Basic Display API
Through Instagram Graph API

Instagram Basic Display API is limited to read-only access to a user’s profile and isn’t intended for user authentication. It’s useful, for example, to get up-to-date information about the user’s profile or display their recent posts. It also works with any Instagram account type: personal and professional.

On the other hand, Instagram Graph API allows you to publish posts, moderate comments, search hashtags, and access insights. However, the Graph API can be used only by “professional” accounts which have been paired with a Facebook page. The authentication flow is handled through Facebook Login, and the user can pick which Facebook pages and Instagram accounts are available to the application.

This article is part of a series about Instagram Graph API. Previously, I covered test account and app setup and finding the correct Instagram account ID. In this part, I will show you how to implement the authentication flow for Instagram Graph API with Facebook Login. I will use Node.js, Express, and Passport with the passport-facebook strategy, but the basic ideas are applicable to any language and framework.

Facebook Login Setup

This tutorial assumes you have a Facebook application set up, and an Instagram business account paired with a Facebook page for testing. If not, check my previous tutorial.

We will need to set up Facebook Login for our testing application.

Find your application on the Facebook Developer Portal, and on the Dashboard, set up Facebook Login for Business. If you didn’t select a “Business app type” when creating the application, you may see Facebook Login instead, so choose that – both options will work.

Under Facebook Login Settings, make sure to enable both Client OAuth login and Web OAuth login.

This screen is also where you can add allowed redirect URIs for deployed application. We will run the application only locally, and Facebook allows localhost URLs by default, so there’s no need to add any URL.

Finally, visit application Settings > Basic, and copy the App ID and App Secret. We will need them for the Passport strategy.

Instagram Graph API authentication flow with Passport

With Facebook Login now set up, we can build an authentication flow. I will use the following npm packages:

express server
express-session to handle user data persistence
passport for authentication
passport-facebook for handling Facebook Login flow
dotenv to read secrets from .env file
@superfaceai/one-sdk to get the list of accessible Instagram profiles

Let’s set up the project and install the dependencies:

mkdir instagram-facebook-login-passport
cd instagram-facebook-login-passport
npm install express express-session passport passport-facebook dotenv @superfaceai/one-sdk

Now create a .env file, and paste in the App ID and App Secret values you obtained in Facebook app settings:

BASE_URL=http://localhost:3000
FACEBOOK_CLIENT_ID="App ID from Settings"
FACEBOOK_CLIENT_SECRET="App Secret from Settings"

I have also prepared the BASE_URL variable, since we will be passing the callback URL during the authentication process. Keeping this value configurable makes it easier to take your app to production.

And now, let's create a server.js file with the following content:

const express = require('express');
const session = require('express-session');
const passport = require('passport');
const { Strategy } = require('passport-facebook');
const { SuperfaceClient } = require('@superfaceai/one-sdk');

require('dotenv').config();

const sdk = new SuperfaceClient();

// <1> Serialization and deserialization
passport.serializeUser(function (user, done) {
  done(null, user);
});
passport.deserializeUser(function (obj, done) {
  done(null, obj);
});

// Use the Facebook strategy within Passport
passport.use(
  // <2> Strategy initialization
  new Strategy(
    {
      clientID: process.env.FACEBOOK_CLIENT_ID,
      clientSecret: process.env.FACEBOOK_CLIENT_SECRET,
      callbackURL: `${process.env.BASE_URL}/auth/facebook/callback`,
    },
    // <3> Verify callback
    (accessToken, refreshToken, profile, done) => {
      console.log('Success!', { accessToken, profile });
      return done(null, { profile, accessToken });
    }
  )
);

const app = express();

// <4> Session middleware initialization
app.use(
  session({ secret: 'keyboard cat', resave: false, saveUninitialized: true })
);
app.use(passport.initialize());

// <5> Start authentication flow
app.get(
  '/auth/facebook',
  passport.authenticate('facebook', {
    // <6> Scopes
    scope: ['pages_show_list', 'instagram_basic', 'instagram_content_publish'],
  })
);

// <7> Callback handler
app.get(
  '/auth/facebook/callback',
  passport.authenticate('facebook'),
  async function (req, res, next) {
    try {
      // <8> Obtaining profiles
      const accessToken = req.user.accessToken;
      const sdkProfile = await sdk.getProfile(
        'social-media/publishing-profiles@1.0.1'
      );
      const result = await sdkProfile
        .getUseCase('GetProfilesForPublishing')
        .perform(
          {},
          {
            provider: 'instagram',
            parameters: {
              accessToken,
            },
          }
        );
      const profiles = result.unwrap();

      res.send(
        `
        <h1>Authentication succeeded</h1>
        <h2>User data</h2>
        <pre>${JSON.stringify(req.user, undefined, 2)}</pre>
        <h2>Instagram profiles</h2>
        <pre>${JSON.stringify(profiles, undefined, 2)}</pre>
        `
      );
      next();
    } catch (err) {
      next(err);
    }
  }
);

app.listen(3000, () => {
  console.log(`Listening on ${process.env.BASE_URL}`);
});

Run the server with npm start and visit http://localhost:3000/auth/facebook. You will be redirected to the Facebook login, where you select the Facebook pages and Instagram profiles the application can have access to. Make sure to select the correct Facebook page with the associated Instagram profile. Otherwise, you won’t be able to access that profile.

After passing the flow, you should see the basic data about your profile and a list of Instagram profiles you have access to.

Explaining the example code

If you read my tutorial on Twitter OAuth 2.0 authentication, the example will seem very familiar. The most significant difference is the handling of access tokens and additional logic for obtaining Instagram profiles.

I will explain the example in individual parts:

User serialization and deserialization

// <1> Serialization and deserialization
passport.serializeUser(function (user, done) {
  done(null, user);
});
passport.deserializeUser(function (obj, done) {
  done(null, obj);
});

These functions serialize and deserialize the user to and from a session. In our example application, we keep all sessions in memory with no permanent storage, so we just pass the whole user object.

Typically, you will persist the data in a database. In that case, you will store the user ID in the session, and upon deserialization, find the user in your database using the serialized ID, for example:

passport.serializeUser(function (user, done) {
  done(null, user.id);
});
passport.deserializeUser(function (id, done) {
  User.findOrCreate(id).then(user => done(null, user));
});

The deserialized user object is then accessible through the req.user property in middleware functions. You can find more in the Passport documentation on sessions.

Strategy initialization

// Use the Facebook strategy within Passport
passport.use(
  // <2> Strategy initialization
  new Strategy(
    {
      clientID: process.env.FACEBOOK_CLIENT_ID,
      clientSecret: process.env.FACEBOOK_CLIENT_SECRET,
      callbackURL: `${process.env.BASE_URL}/auth/facebook/callback`,
    }
    // ...
  )
);

This code registers the passport-facebook strategy with credentials obtained from the application settings. The callback URL must be absolute, and registered as a valid OAuth redirect URL (except for localhost).

Success callback

passport.use
  new Strategy(
    // ...
        ,
    // <3> Verify callback
    (accessToken, refreshToken, profile, done) => {
      console.log('Success!', { accessToken, profile });
      return done(null, { profile, accessToken });
    }
  )
);

The second argument to the strategy constructor is a verify function, which is called at the end of the successful authorization flow. The user has authorized your application, and you will receive their access token and basic information about their profile (in this case just the ID and full name of the user). Facebook API doesn’t provide refreshToken (you can, instead, turn the access token into a long-lived token), therefore that value will be always empty.

Here, you might want to update or create the user in your database and store the access token, so that you can access the API on behalf of the user. The done callback should receive a user object, which is later available through req.user. To keep things simple, I only passed the access token along with the profile data.

Passport and Session middlewares initialization

// <4> Session middleware initialization
app.use(
  session({ secret: 'keyboard cat', resave: false, saveUninitialized: true })
);
app.use(passport.initialize());

Passport needs to be initialized as middleware as well. And it requires a session middleware for storing state and user data. The most common session middleware is express-session.

By default, express-session stores all data in memory, which is good for testing, but not intended for production: if your server gets restarted, all users will be logged out. There is a wide selection of compatible session stores – pick one which fits with the rest of your stack.

Before you put this code into production, make sure to change the value of secret. This value is used to sign the session cookie. Keeping it easily guessable increases the risk of session hijacking. Check the express-session docs.

Start the authentication flow

Now we are getting to the actual route handlers where the authentication happens.

// <5> Start authentication flow
app.get(
  '/auth/facebook',
  passport.authenticate('facebook', {
    // <6> Scopes
    scope: ['pages_show_list', 'instagram_basic', 'instagram_content_publish'],
  })
);

passport.authenticate creates a middleware for the given strategy. It redirects the user to Facebook with URL parameters, so that Facebook knows what application is the user authorizing and where the user should be then redirected back. The authenticate function accepts a second parameter with additional options, where the most important is scopes.

Authorization scopes (permissions)

passport.authenticate('facebook', {
  // <6> Scopes
  scope: ['pages_show_list', 'instagram_basic', 'instagram_content_publish'],
});

OAuth scopes define what the application is allowed to do on behalf of the user (Facebook calls them “permissions”). The user can then review and approve these permissions.

In this case, we request the following permissions:

pages_show_list to list Facebook pages the user manages and allowed for our app
instagram_basic to read basic information about an Instagram profile
instagram_content_publish to allow publishing content; this is not needed now, but may be useful in the next tutorial.

You can find additional possible permissions in the Permissions Reference. Keep in mind that if you’d like your application to be publicly accessible, you will have to submit it for an app review, and explain how permissions are used.

Callback handler

// <7> Callback handler
app.get(
  '/auth/facebook/callback',
  passport.authenticate('facebook'),
  async function (req, res, next) {
    // ...
  }
);

This is the final step in the authentication flow. After the user authorized your application, they are redirected to the /auth/twitter/callback route. The passport.authenticate middleware is here again, but this time it checks the query parameters Facebook provided on redirect, and obtains access and refresh tokens.

If the authentication succeeds, the next middleware function is called – typically you will display some success message to the user, or redirect them back to your application. Since the authentication passed, you can now find the user data in the req.user property.

Obtaining Instagram profiles

async function (req, res, next) {
  try {
    // <8> Obtaining profiles
    const accessToken = req.user.accessToken;
    const sdkProfile = await sdk.getProfile(
      'social-media/publishing-profiles@1.0.1'
    );
    const result = await sdkProfile
      .getUseCase('GetProfilesForPublishing')
      .perform(
        {},
        {
          provider: 'instagram',
          parameters: {
            accessToken,
          },
        }
      );
    const profiles = result.unwrap();

    res.send(
      `
      <h1>Authentication succeeded</h1>
      <h2>User data</h2>
      <pre>${JSON.stringify(req.user, undefined, 2)}</pre>
      <h2>Instagram profiles</h2>
      <pre>${JSON.stringify(profiles, undefined, 2)}</pre>
      `
    );
    next();
  } catch (err) {
    next(err);
  }
}

The route handler uses Superface OneSDK to fetch basic data about Instagram profiles we have access to. I use GetProfilesForPublishing for that, which also works with Facebook, LinkedIn, Pinterest, and Twitter. The logic is the same as in the previous Find the right account ID tutorial, except we are passing the access token stored in session from req.user.accessToken (see the code for the Success callback).

Next steps

One issue with the example code is that both the user data and the access token are stored in memory. The user needs to go through the authentication flow every time the server is restarted. For a real-world use, you will need to persist the data using, for example, a configuration file or a database.

In future tutorials, I will look at publishing of images and videos, searching hashtags, and retrieving posts and comments. If you don’t want to miss them, subscribe to our newsletter and follow our blog 👇

Superface Follow

Superface allows GPT builders to easily connect to any API, enabling them to create, retrieve, and manage data from external platforms.

Did you run into any problems? I will be happy to help you on our Discord!

Let's build a contact form with Next.js

Dexter — Thu, 29 Dec 2022 12:58:17 +0000

Most of the websites have a contact page where you can send a message to reach the owner. They look something like this:

In this article, we will create a similar form with React in Next.js. First, I will create a front-end part with the form, and then I will build an API route which will send the form to your email.

Setting up the application

First, let’s create a new Next.js project. We will create it in a contact-form folder, with JavaScript and ESLint enabled:

npx create-next-app contact-form --js --eslint

This will create the folder and installs all the dependencies.

Now enter the folder (cd contact-form) and start the development server:

npm run dev

Visit http://localhost:3000 to check the running application.

Creating the form

The main file where we are going to make changes is pages/index.js. Remove the original code inside the file and paste the following code:

import React from 'react';

export default function Home() {
  return (
    <form className="container">
      <h1>Get in touch</h1>
      <div className="email block">
        <label htmlFor="frm-email">Email</label>
        <input
          id="frm-email"
          type="email"
          name="email"
          autoComplete="email"
          required
        />
      </div>
      <div className="block phone">
        <label htmlFor="frm-phone">Phone</label>
        <input
          id="frm-phone"
          type="text"
          name="phone"
          autoComplete="tel"
          required
        />
      </div>
      <div className="name block">
        <div>
          <label htmlFor="frm-first">First Name</label>
          <input
            id="frm-first"
            type="text"
            name="first"
            autoComplete="given-name"
            required
          />
        </div>
        <div>
          <label htmlFor="frm-last">Last Name</label>
          <input
            id="frm-last"
            type="text"
            name="last"
            autoComplete="family-name"
            required
          />
        </div>
      </div>
      <div className="message block">
        <label htmlFor="frm-message">Message</label>
        <textarea id="frm-message" rows="6" name="message"></textarea>
      </div>
      <div className="button block">
        <button type="submit">Submit</button>
      </div>
    </form>
  );
}

This code creates a form with the following fields:

email
first name
last name
phone number
message

All fields are required except for the message.

To add style to the form, replace the contents of styles/globals.css file with the following code:

html,
body {
  padding: 0;
  margin: 0;
  font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Oxygen, Ubuntu,
    Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif;
  background: #1e1e1e;
  min-height: 100vh;
  display: flex;
  color: rgb(243, 241, 239);
  justify-content: center;
  align-items: center;
}

.block {
  display: flex;
  flex-direction: column;
}

.name {
  display: flex;
  flex-direction: row;
  justify-content: space-between;
}

.container {
  font-size: 1.3rem;
  border-radius: 10px;
  width: 85%;
  padding: 50px;
  box-shadow: 0 54px 55px rgb(78 78 78 / 25%), 0 -12px 30px rgb(78 78 78 / 25%),
    0 4px 6px rgb(78 78 78 / 25%), 0 12px 13px rgb(78 78 78 / 25%),
    0 -3px 5px rgb(78 78 78 / 25%);
}

.container input {
  font-size: 1.2rem;
  margin: 10px 0 10px 0px;
  border-color: rgb(31, 28, 28);
  padding: 10px;
  border-radius: 5px;
  background-color: #e8f0fe;
}

.container textarea {
  margin: 10px 0 10px 0px;
  padding: 5px;
  border-color: rgb(31, 28, 28);
  border-radius: 5px;
  background-color: #e8f0fe;
  font-size: 20px;
}

.container h1 {
  text-align: center;
  font-weight: 600;
}

.name div {
  display: flex;
  flex-direction: column;
}

.block button {
  padding: 10px;
  font-size: 20px;
  width: 30%;
  border: 3px solid black;
  border-radius: 5px;
}

.button {
  display: flex;
  align-items: center;
}

textarea {
  resize: none;
}

Our form should look something like this:

Now we need to find a way to store the input entered by the user. I will use FormData which is natively supported in all current browsers. It loads fields from the form, so they can be then submitted to the server.

Inside the pages/index.js file, paste the following code (notice the new handleSubmit function):

import React from 'react';

export default function Home() {
  async function handleSubmit(e) {
    e.preventDefault();
    const data = new FormData(e.currentTarget);
    console.log(data);
  }

  return (
    <form className="container" onSubmit={handleSubmit}>
      <h1>Get in touch</h1>
      <div className="email block">
        <label htmlFor="frm-email">Email</label>
        <input
          id="frm-email"
          type="email"
          name="email"
          autoComplete="email"
          required
        />
      </div>
      <div className="block phone">
        <label htmlFor="frm-phone">Phone</label>
        <input
          id="frm-phone"
          type="text"
          name="phone"
          autoComplete="tel"
          required
        />
      </div>
      <div className="name block">
        <div>
          <label htmlFor="frm-first">First Name</label>
          <input
            id="frm-first"
            type="text"
            name="first"
            autoComplete="given-name"
            required
          />
        </div>
        <div>
          <label htmlFor="frm-last">Last Name</label>
          <input
            id="frm-last"
            type="text"
            name="last"
            autoComplete="family-name"
            required
          />
        </div>
      </div>
      <div className="message block">
        <label htmlFor="frm-message">Message</label>
        <textarea id="frm-message" rows="6" name="message"></textarea>
      </div>
      <div className="button block">
        <button type="submit">Submit</button>
      </div>
    </form>
  );
}

Now when you attempt to submit the form, you should see FormData in developer console.

Submitting the form to API

We will submit the form data to the API with [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) – no need for additional dependencies.

The form submission logic goes to the handleSubmit function. Here is the complete code in pages/index.js:

import React from 'react';

export default function Home() {
  async function handleSubmit(e) {
    e.preventDefault();
    const data = new FormData(e.currentTarget);
    try {
      const response = await fetch('/api/contact', {
        method: 'post',
        body: new URLSearchParams(data),
      });
      if (!response.ok) {
        throw new Error(`Invalid response: ${response.status}`);
      }
      alert('Thanks for contacting us, we will get back to you soon!');
    } catch (err) {
      console.error(err);
      alert("We can't submit the form, try again later?");
    }
  }

  return (
    <form className="container" onSubmit={handleSubmit}>
      <h1>Get in touch</h1>
      <div className="email block">
        <label htmlFor="frm-email">Email</label>
        <input
          id="frm-email"
          type="email"
          name="email"
          autoComplete="email"
          required
        />
      </div>
      <div className="block phone">
        <label htmlFor="frm-phone">Phone</label>
        <input
          id="frm-phone"
          type="tel"
          name="phone"
          autoComplete="tel"
          required
        />
      </div>
      <div className="name block">
        <div>
          <label htmlFor="frm-first">First Name</label>
          <input
            id="frm-first"
            type="text"
            name="first"
            autoComplete="given-name"
            required
          />
        </div>
        <div>
          <label htmlFor="frm-last">Last Name</label>
          <input
            id="frm-last"
            type="text"
            name="last"
            autoComplete="family-name"
            required
          />
        </div>
      </div>
      <div className="message block">
        <label htmlFor="frm-message">Message</label>
        <textarea id="frm-message" rows="6" name="message"></textarea>
      </div>
      <div className="button block">
        <button type="submit">Submit</button>
      </div>
    </form>
  );
}

The handleSubmit sends data inside a POST request to the /api/contact route. We also wrap the FormData object in URLSearchParams to send data as application/x-www-form-urlencoded which is automatically decoded by Next.js API routes handler.

Handling form submission in the API route

Now we need to handle the form submission on the server. We are going to use Next.js API routes for that. API routes are located in pages/api folder. Let’s create pages/api/contact.js file which corresponds to the API route /api/contact.

First inside the pages/api/contact.js file paste the following code to test if we receive the data on the server.

export default function handler(req, res) {
  console.log(req.body);
  res.send(200);
}

Try submitting the form now, you should see the data logged on the terminal. And now we are getting to the juicy part.

Sending emails with SendGrid and Superface

When a user submits the contact form, we want to send the submitted information to the website owner. First, we need to pick some email providers and study their API and SDK. Or we can use Superface with any provider.

Superface makes API integrations super easy. We don’t have to deal with API docs, and I can use many providers behind the same interface. Furthermore, I can use more ready-made API use cases from the Superface catalog. It’s a tool worth having in your toolbox.

Set up SendGrid

I’m going to use SendGrid as an email provider with Superface. Create your account, get your API key with Full Access and verify Single Sender Verification.

On Superface side, pick the use case, i.e.: Send Email.

Sending emails from the API route

Superface use cases are consumed with OneSDK, so we will have to install it.

npm i @superfaceai/one-sdk

On Superface in Send Email use case, select sendgrid as a provider. We can use most of the code from the example in our API route handler, we just need to pass data correctly from the request.

Paste the following code into your pages/api/contact.js file:

const { SuperfaceClient } = require('@superfaceai/one-sdk');

const sdk = new SuperfaceClient();

// Just check if all required fields are provided
function formValid(body) {
  return body.email && body.phone && body.first && body.last;
}

export default async function handler(req, res) {
  const body = req.body;

  if (!formValid(body)) {
    res.status(422).end();
    return;
  }

  const profile = await sdk.getProfile('communication/send-email@2.1.0');
  const message = `
    Email: ${body.email}
    Phone: ${body.phone}
    Name: ${body.first} ${body.last}
    Message: ${body.message} 
    `;
  const result = await profile.getUseCase('SendEmail').perform(
    {
      from: process.env.FROM_EMAIL,
      to: process.env.TO_EMAIL,
      subject: 'Message from contact form',
      text: message,
    },
    {
      provider: 'sendgrid',
      security: {
        bearer_token: {
          token: process.env.SENDGRID_API_KEY,
        },
      },
    }
  );

  try {
    const data = result.unwrap();
    console.log(data);
    res.status(201).end();
  } catch (error) {
    console.error(error);
    res.status(500).end();
  }
}

You can notice that we are referring to some environment variables in the code (for example process.env.SENDGRID_TOKEN). We can store these in .env files. In the root of your project, create a .env.local file with the following contents (make sure to edit values):

# Email address verified in Single Sender Verification
FROM_EMAIL=from@example.com
# Email address where you want to send the submissions to
TO_EMAIL=to@example.com
# Sendgrid API key
SENDGRID_API_KEY=SG.abcdef...

Our app is ready. Run (or restart) the development server with npm run dev and try to submit the form!

Conclusion

We have learned how to create a form in Next.js, submit the form with FormData and fetch, handle the submission in the API route and send it through an email.

Further possible improvements include adding CAPTCHA or honeypot fields to prevent spam submissions, improving form data validation with checks of phone and email address, format the submission as HTML, or providing a nicer feedback to the user upon submissions.

Besides sending an email, we can do a lot more with submissions, like sending data to CRM or Slack, or handle newsletter subscriptions. But that’s for another time – follow our profile or sign up for our monthly newsletter, so you don't miss our future tutorials.

How to use Twitter OAuth 2.0 and Passport.js for user login

Jan Vlnas — Thu, 24 Nov 2022 13:26:43 +0000

tl;dr Use the Node.js package @superfaceai/passport-twitter-oauth2 to handle user authentication with Twitter's v2 API and Passport.js.

superfaceai / passport-twitter-oauth2

Twitter OAuth 2.0 Strategy for Passport for accessing Twitter API v2

Twitter OAuth 2.0 Strategy for Passport

@superfaceai/passport-twitter-oauth2

Passport strategy for authenticating with Twitter using OAuth 2.0.

This module lets you authenticate using Twitter in your Node.js applications By plugging into Passport, Twitter authentication can be integrated into any application or framework that supports Connect-style middleware, including Express.

Twitter announced OAuth 2.0 general availability on December 14 2021 and encourages developers to use Twitter API v2.0 with OAuth 2.0 authentication.

Twitter OAuth 2.0 implementation specifics:

PKCE is required
OAuth2 client credentials must be passed via Authorization header for confidential client types

Install

npm install @superfaceai/passport-twitter-oauth2

Usage

Note Check our blog for a complete tutorial with code explanation.

Create an Application

Before using @superfaceai/passport-twitter-oauth2, you must register a project and an application with Twitter by following these steps:

go to https://developer.twitter.com/ and either sign up for a new account or sign in with existing one
sign up…

View on GitHub

Read on for the background, how to obtain Twitter credentials, example Express app, and code explanation.

Why use OAuth 2.0 for Twitter API

When you want to interact with Twitter's API or just provide a “social login” through Twitter, until last year you had to use legacy OAuth 1.0a authentication. While it still has its uses, Twitter is transitioning to the new version of their API (v2) and OAuth 2.0 protocol, which is also used by other providers, like Facebook, Google, and LinkedIn.

Besides being more widespread, Twitter's OAuth 2.0 has other advantages compared to OAuth 1.0a:

It gives you full access to Twitter's v2 API (including the endpoints for Twitter Spaces and editing tweets)
It lets you specify exactly what your application needs from the API through scopes, so users have a clear idea what your app can and cannot do with their account; OAuth 1.0a has only three levels of access: “read”, “read + write”, and “read + write + access DMs”
It is future-proof, as the development effort is focused on v2 API, for which OAuth 2.0 is the default authentication protocol.

When we wanted to build social media integrations, we couldn't find any up-to-date Node.js library to handle the authentication flow. So, we built one as a strategy for the popular Passport.js authentication middleware.

The strategy is available in @superfaceai/passport-twitter-oauth2 package. Recently we released a new minor version 1.2, which conducts a full rewrite to TypeScript.

Getting OAuth 2.0 Client ID and Secret from Twitter

To start using Twitter API, you need to register for a developer account (including phone number verification). Once you register, you will be prompted to create the first application. You will immediately receive API Key and API Key Secret – but ignore them, since these are only for OAuth 1.0. Instead, go to your project's dashboard, there go to the App Settings of the only application you created.
In application settings, find User authentication settings and click Set up.

In User authentication settings make sure to select Type of App as Web App, Automated App or Bot.

In App info enter the following URL under Callback URI / Redirect URL:

http://localhost:3000/auth/twitter/callback

This is a URL where the user can be redirected after approving the application. The callback will be handled by the example server we will build in the next section.

Fill in also the Website URL, since it is a required value. Feel free to ignore other fields.

Once you save the form, you will get OAuth 2.0 Client ID and Client Secret. Make sure to write these values down, since you can't reveal the secret later, only regenerate it.

But in case you forget to save the secret, you can always regenerate it under Keys and Tokens section of your app.

Authenticating with Passport.js and Twitter in Express.js

Let's create a simple Express server with Passport.js to show the authentication flow in action. Passport requires some session handling mechanism, usually through express-session. I will also use the dotenv package to load the credentials from .env file to process.environment object.

First, let's create a project and install dependencies:

mkdir twitter-oauth2-passport-demo
cd twitter-oauth2-passport-demo
npm install express express-session passport @superfaceai/passport-twitter-oauth2 dotenv

Now put your Client ID and Client Secret into .env file in the root of your project. Use the following template and make sure to paste in the correct values from the developer portal:

BASE_URL=http://localhost:3000
TWITTER_CLIENT_ID="OAuth 2.0 Client ID from Twitter Developer portal"
TWITTER_CLIENT_SECRET="OAuth 2.0 Client Secret from Twitter Developer portal"

I have also prepared the BASE_URL variable, since we will be passing the callback URL during the authentication, and keeping this value configurable makes it easier to take your app to production.
And now, let's create server.js file, and put in the following contents:

const express = require('express');
const passport = require('passport');
const { Strategy } = require('@superfaceai/passport-twitter-oauth2');
const session = require('express-session');
require('dotenv').config();

// <1> Serialization and deserialization
passport.serializeUser(function (user, done) {
  done(null, user);
});
passport.deserializeUser(function (obj, done) {
  done(null, obj);
});

// Use the Twitter OAuth2 strategy within Passport
passport.use(
  // <2> Strategy initialization
  new Strategy(
    {
      clientID: process.env.TWITTER_CLIENT_ID,
      clientSecret: process.env.TWITTER_CLIENT_SECRET,
      clientType: 'confidential',
      callbackURL: `${process.env.BASE_URL}/auth/twitter/callback`,
    },
    // <3> Verify callback
    (accessToken, refreshToken, profile, done) => {
      console.log('Success!', { accessToken, refreshToken });
      return done(null, profile);
    }
  )
);

const app = express();

// <4> Passport and session middleware initialization
app.use(passport.initialize());
app.use(
  session({ secret: 'keyboard cat', resave: false, saveUninitialized: true })
);

// <5> Start authentication flow
app.get(
  '/auth/twitter',
  passport.authenticate('twitter', {
    // <6> Scopes
    scope: ['tweet.read', 'users.read', 'offline.access'],
  })
);

// <7> Callback handler
app.get(
  '/auth/twitter/callback',
  passport.authenticate('twitter'),
  function (req, res) {
    const userData = JSON.stringify(req.user, undefined, 2);
    res.end(
      `<h1>Authentication succeeded</h1> User data: <pre>${userData}</pre>`
    );
  }
);

app.listen(3000, () => {
  console.log(`Listening on ${process.env.BASE_URL}`);
});

Now run your server with npm start and visit http://localhost:3000/auth/twitter. You will be redirected to Twitter authorization page:

And once you authorize the app, you should see the user data from your profile and, in addition, accessToken and refreshToken will be logged into console.

Breaking down the example

Let's break down the example code above a bit.

User serialization and deserialization

// <1> Serialization and deserialization
passport.serializeUser(function (user, done) {
  done(null, user);
});
passport.deserializeUser(function (obj, done) {
  done(null, obj);
});

These functions serialize and deserialize user to and from session. In our example application, we keep all sessions in the memory with no permanent storage, so we just pass the whole user object.

Typically, you will persist data in a database. In that case, you will store the user ID in the session, and upon deserialization find the user in your database using the serialized ID, for example:

passport.serializeUser(function (user, done) {
  done(null, user.id);
});
passport.deserializeUser(function (id, done) {
  User.findOrCreate(id).then(user => done(null, user));
});

The deserialized user object is then accessible through req.user property in middleware functions.

Strategy initialization

// Use the Twitter OAuth2 strategy within Passport
passport.use(
  // <2> Strategy initialization
  new Strategy(
    {
      clientID: process.env.TWITTER_CLIENT_ID,
      clientSecret: process.env.TWITTER_CLIENT_SECRET,
      clientType: 'confidential',
      callbackURL: `${process.env.BASE_URL}/auth/twitter/callback`,
    }
    // ...
  )
);

To use an authentication strategy, it must be registered with Passport through passport.use. Here, the Twitter OAuth 2.0 strategy is initialized with credentials from Twitter developer portal. The callback URL must be absolute and registered with Twitter – it's where the user is redirected after authorizing the application.

clientType can be either confidential or public, but in case of server-side applications you will usually use confidential. As explained in OAuth specification, confidential clients can keep the secret safe, while public clients, like mobile applications, can't.

Success callback

passport.use(
  new Strategy(
    //...
    ,
    // <3> Verify callback
    (accessToken, refreshToken, profile, done) => {
      console.log('Success!', { accessToken, refreshToken });
      return done(null, profile);
    }
  )
);

The second argument to the strategy constructor is a verify function. In case of OAuth-based strategies, it is called at the end of successful authorization flow. The user has authorized your application, and you will receive their access token and (optionally) refresh token and user's profile (username, display name, profile image etc.).

Now it's your turn: typically you will want to update or create the user in your database and store the tokens, so you can call the API with them. The done callback should receive a user object, which is passed in req.user property.

Passport and Session middlewares initialization

// <4> Passport and session middleware initialization
app.use(passport.initialize());
app.use(
  session({ secret: 'keyboard cat', resave: false, saveUninitialized: true })
);

Passport needs to be initialized as middleware as well. And it requires a session middleware for storing state and user data. The most common session middleware is express-session.

Start the authentication flow

Now we get to the juicy part, routes where the authentication happens. The first route is /auth/twitter:

// <5> Start authentication flow
app.get(
  '/auth/twitter',
  passport.authenticate('twitter', {
    //...
  })
);

passport.authenticate creates a middleware for the given strategy. It redirects the user to Twitter with URL parameters, so Twitter knows what application the user is authorizing and where the user should be then redirected back. authenticate function accepts a second parameter with additional options, where the most important is scopes.

Authorization scopes

passport.authenticate('twitter', {
  // <6> Scopes
  scope: ['tweet.read', 'users.read', 'offline.access'],
});

OAuth scopes define what the application is allowed to do on behalf of the user. The user can then review and approve these permissions.

In this case, the following scopes are requested:

tweet.read – allows reading of user's and others' tweets (including tweets from private accounts the user follows)
users.read – allows reading information about users profiles
offline.access – allows access even when the user isn't signed in; in practice, the application receives the refresh token

Both tweet.read and users.read are necessary for accessing information about the signed-in user. offline.access is useful when you want to do something when the user isn't directly interacting with your application, for example if you post scheduled tweets, build a bot, or monitor mentions on Twitter.

For a detailed overview of what scopes are used in Twitter's API, check Twitter's authentication mapping.

Callback handler

// <7> Callback handler
app.get(
  '/auth/twitter/callback',
  passport.authenticate('twitter'),
  function (req, res) {
    const userData = JSON.stringify(req.user, undefined, 2);
    res.end(
      `<h1>Authentication succeeded</h1> User data: <pre>${userData}</pre>`
    );
  }
);

This is the final step in the authentication flow. After the user authorized your application, they are redirected to /auth/twitter/callback route. The passport.authenticate middleware is here again, but this time it checks query parameters Twitter provided on redirect, checks if everything is correct, and obtains access and refresh tokens.

If the authentication succeeds, the next middleware function is called – typically you will display some success message to the user or redirect them back to your application. Since the authentication passed, you can now find the user data in req.user property.

Next steps

Passport.js isn't limited to just Express, you can use our strategy with other frameworks with Passport compatibility like NestJS, Fastify, or Koa.

With the obtained access token, you can start integrating Twitter's API. Check out our twitter-demo repository with CLI scripts showing how to list followers, lookup posts by hashtag, or publish a tweet.

We also have a bit more complex social-media-demo which demonstrates authentication and integrations with Facebook, Instagram, LinkedIn, and Twitter.

I will be diving into more hands-on examples with Twitter, Instagram, and other social media in the future posts. Subscribe to our blog or sign up for our monthly newsletter, so you don't miss it.

Superface Follow

Superface allows GPT builders to easily connect to any API, enabling them to create, retrieve, and manage data from external platforms.

Try our strategy and let me know what you are building with it!

Resources

Announcement of OAuth 2.0 General Availability by Twitter
Twitter's guide Getting Access to the Twitter API is useful for the general overview of required steps and use of various credentials.
Twitter API v2 authentication mapping for overview of what scopes are needed where.
OAuth 2.0 Authorization Code Flow with PKCE explains details of Twitter's OAuth 2.0 implementation, like lifetime of access and refresh tokens, glossary, and overview of all scopes.

AI in APIs

Wed, 16 Nov 2022 12:08:13 +0000

Artificial Intelligence (AI) is making its way into everyday developer life, but the use of AI along the API lifecycle is yet to be improved. For decades APIs have relied on tedious manual work. Tasks like API design, API documentation, discovery, contract, and API integration are primarily manual, but a change is coming.

APIs can leverage AI, and AI can significantly benefit from APIs. Though the use of AI in APIs is a vast topic, we will split it into two. The first is employing AI (precisely ML – machine learning algorithms) to deliver or integrate APIs. The second topic is enabling AI, which can either mean making AI accessible via APIs or making the APIs accessible to an AI.

Using AI in APIs

Using AI/ML can enhance a developer's life, boost efficiency, and lead to better applications and shorter delivery times. Following are a few examples of employing AI in APIs delivery and consumption.

AI client and server code-gen

The most straightforward use of AI/ML is to generate API calls or server code on behalf of a programmer. Solutions like GitHub Copilot can create code stubs, reducing developers' need to write the API calls boilerplate. As a larger corpus of API calls is needed, this approach is primarily suitable for public APIs.

API client code generation with GitHub Copilot

AI API design

A good API design is a function of developer experience and operational efficiency. Algorithm-guided API design can improve the efficient layout of resources. Traffic recording and profiling information from API observability tools (Akita, Optic, Seekret, …) already provide valuable insights and can be the input for the AI-guided API design.

AI can also aid in designing APIs from the ground up, mapping the use cases into correct API protocol/style semantics. For example, from the operation name "make payment," the algorithm may infer an unsafe, idempotent operation and, therefore, the POST HTTP method.

Jurrasic-X assists in mapping a use case to an HTTP method

AI API integration

The opposite approach to AI-guided API design is that an algorithm can infer what operation to invoke, what the parameters are, and how to map them from the user input to the expected result. These algorithms can take a business case for an API (e.g., "how to fulfill an order") and API documentation as input and figure out the required API communication to complete the use case.

OpenAI GPT-3 aiding with API integration

AI API security

Currently, the most mature area is using AI/ML algorithms to analyze valuable information from the API traffic. For example, an algorithm can check whether there are sensitive data in the traffic or when a malicious communication pattern threatens your systems. The existing tools (Traceable, Aiculus) already help security, DevOps, and compliance teams in their work.

Levels of enabling AI

Beyond helping developers deliver or consume APIs, AI can greatly benefit from them. Here's how APIs will gradually enable AI.

1. APIs as the interface to AI

APIs are vital in making AI and its infrastructure accessible to other applications. Many AI/ML models and algorithms are proprietary (OpenAI) or resource-consuming, so they can't be self-hosted by their users. API is the standard way to make AI available in these cases. The same applies to AI/ML and data science infrastructure (Google, Azure, AWS), where users can develop and run their models.

2. Self-integrating applications

Self-integrating applications are the revolutionary step in distributed systems. It enables applications to integrate without the need for human intervention. This integration can be direct between two applications or via an intermediary – an integration platform.

Advanced integration platforms can infer common integration patterns, and when a new application enters the organizational landscape, it can be automatically hooked into the existing applications.

Several integration platforms already employ algorithms to assist engineers in their repetitive tasks of data mapping and system integrations (Dell Boomi, Snaplogic). Still, we need the new infrastructure to enable applications to integrate without assistance.

Superface is the pioneer in direct self-integrating applications, enabling them to integrate autonomously without needing an intermediary.

3. Autonomous applications

An autonomous application can navigate and make decisions in its landscape. Unlike a self-integrating application, an autonomous application can decide which API to connect and when.

The critical difference to the present API clients is that the autonomous applications are programmed for a job, not how the job is executed with a particular API at a given time.

To illustrate, a manufacturing application can be programmed to check the status of the works on the product. However, it is not instructed on how to do it and what APIs to ask. Instead, when executed within a landscape, the application will determine what APIs are available and which ones to call to get the answer.

Autonomous application conceptual scheme

4. Autonomous Business Integrations

Autonomous business integrations take the concept of autonomous application to the next level. The application can discover and connect to an API without human intervention, but it can also enter a business contract on its user's behalf. The autonomous business integrations (ABI) will fully unlock the digital business-making where software can evaluate, enter or fulfill contracts.

An example would be a commerce application that needs to send text messages to its users in various countries. At any given time, such an application can quickly evaluate all available API providers, their costs and quality, make the purchase, and send the messages at the best price and quality.

5. AI applications

The pinnacle of interfaces for AI is a system where the tasks are not hard-coded in the application. Instead, the application can infer (e.g., for a user's input) what job to execute, the available APIs in its landscape to fulfill the task, and which one to use. This ultimate step will unlock the reasoning AI that would be able to navigate in the universe of humanity's capabilities.

But if the technological Singularity can happen, it will.

– Vernor Vinge

At Superface.ai, we are committed to researching and advancing AI in APIs. We have released the infrastructure for self-integrating applications and are heading forward to introducing the autonomous business integrations and, at a later stage, towards the AI systems.

If you are working in one of the areas, or you think I've missed one, let me know in comments!

How do you glue APIs together?

Jan Vlnas — Fri, 11 Nov 2022 13:56:44 +0000

Say you want to connect two or more APIs, for example:

Whenever someone submits a form on our website, add their contact to HubSpot (or other CRM) and email them.
When someone gives a star to my repository on GitHub, send me a Telegram message.
Post a tweet when there's a new post on our blog.

How do you connect these different API integrations together?

Do you use some low-code platform like Zapier, n8n, or Node-RED? Or do you prefer to “glue” the code manually? Or do you have a magical framework which does the hard work for you?

And importantly, how much you like/hate your current approach, and how do you think it should work?

I am curious to know!