GraphQL API

The GraphQL API provides communication with the SmartFaces using a query language, where the response to your queries is being fulfilled on runtime using your existing data. You can ask SmartFace exactly what you need and nothing more, making it easier to to keep up to date with the platform.

Use the GraphQL API and get exactly what you need, nothing more and nothing less. This approach is in contrast to traditional REST APIs, where the server determines the structure and content of the response. GraphQL always returns predictable results. Apps using GraphQL are fast and stable because they control the data they get, not the server. We support two ways to use the GraphQL:

• GraphQL Queries
• GraphQL Subscriptions

Both of the options are accesible per default at your installation’s port 8097 under graphql endpoint. An example URL would be http://localhost:8097/graphql. We are using the Banana Cake Pop at the endpoint.

GraphQL Queries#

What is a GraphQL Query#

A GraphQL query is a request made by a client to a GraphQL server for specific data. Key characteristics of a GraphQL query include:

• Declarative: In a GraphQL query, the client specifies exactly what data it wants and the shape of the response. This makes it highly declarative and eliminates over-fetching or under-fetching of data.
• Hierarchical: GraphQL queries are hierarchical and mirror the structure of the data being requested. The query consists of fields and subfields that correspond to the structure of the data on the server.
• Single Endpoint: Unlike REST, which often involves multiple endpoints for different resources, GraphQL typically exposes a single endpoint for all queries and mutations. Clients can request the specific data they need from this single endpoint.
• Strongly Typed: GraphQL uses a type system to define the structure of the data. Clients can introspect the schema to understand what data is available and what types are expected for each field.

How to write a GraphQL Query#

Here’s an example of a GraphQL query used in a SmartFace:

query
{
  matchResults 
  {
    items 
    {
      createdAt
      watchlistMemberFullName
      watchlistMemberDisplayName
      watchlistFullName
      watchlistDisplayName
      score
    }
  }
}

You can use such an example to get all match results and it’s items with provided data for attributes createdAt, watchlistMemberFullName, watchlistMemberDisplayName, watchlistFullName, watchlistDisplayName, and score. As you can write your own query, you can easily add additional attributes. The attributes are are described in the schema reference and definition available in the graphql endpoint. While typing your query when you use the CTRL+SPACE shortcut, suggestion dropdown appears to let you know additional options.

The SmartFace’s GraphQL API has a limit of 1000 items per response. We would suggest pagination per 1000 items. Please see an example below:

query 
{
  genericObjects(take:1000,skip:0,order: {createdAt: ASC}) 
  {
    items 
    {
      objectType
      genericObjectType
      createdAt
      streamId
      imageDataId
      quality
      cropRightTopX
      cropRightTopY
      cropLeftBottomX
      cropLeftBottomY
      objectAttributes 
      {
        type
        floatValue
        boolValue
        visualObjectId
        __typename
      }     
    }
  }
}

How to access GraphQL Query programatically#

On top of using the GraphQL via the Banana Cake Pop, you can use the GraphQL queries with you favourite programming language.

We have several examples how to use the SmartFace’s GraphQL Queries programatically on our SmartFace Integration’s github.

• Python - if you are interested in an example of the SmartFace’s GraphQL Query for the python language, please take a look at the GetAllImagesFromPerson script
• C# - if you are interested in an example of the SmartFace’s GraphQL Query for the C# language. please take a look at the ExportFacesWithImages application

GraphQL Subscriptions#

What is a GraphQL Subscription#

A GraphQL subscription is a real-time data query in GraphQL that allows clients to receive updates the SmartFace when specific events or changes occur on the server. The provided data, events and changes are related to your request. Subscriptions enable the server to push data to connected clients, creating a real-time communication channel between the client application and the SmartFace.

Key characteristics of GraphQL subscriptions:

• Real-Time Updates: GraphQL subscriptions are designed for real-time data synchronization. They are particularly useful for applications that require live updates - any scenario where data changes need to be immediately reflected on the client.

• Event-Driven: Subscriptions are event-driven. Clients specify the events they want to subscribe to, such as “faceCreated,” “pedestrianInserted,” or “matchResult,” and the server sends updates whenever those events occur.

• Persistent Connections: Subscriptions typically rely on WebSocket connections to maintain a persistent connection between the client and the server. This enables the server to push updates to the client as soon as they become available, rather than requiring the client to repeatedly poll for changes.

• Similar Syntax to Queries: The syntax for defining and using GraphQL subscriptions is similar to that of queries. Clients use a subscription operation to specify the event they want to subscribe to and the fields they want in the response.

How to write GraphQL Subscription#

Here’s an example of a GraphQL subscription used in a SmartFace:

subscription{
  matchResult {
    watchlistFullName
    watchlistMemberFullName
    streamId
    spoofCheck {
      performed
      passed
      distantLivenessSpoofCheck {
        performed
        passed
        score
      }
    }
    cropImage
  }
}

You can use such an example to subscribe to the match result events. This means that once subscribed, each time such an event happens, you will receive another response/result.

In the provided subscription code we are expecting to receive for each such match result information about the matched watchlist member - his name and the watchlist where the person belongs to; stream id - unique id of a camera that was used to match the person; information regarding the liveness being performed and whether the matched person is considered a live person or a spoof, and also the crop image of the face is provided in the base64 encoding.

How to access GraphQL Subscription programatically#

On top of using the GraphQL via the Banana Cake Pop, you can use the GraphQL subscriptions with you favourite programming language.

We have several examples how to use the SmartFace’s GraphQL Subscriptions programatically on our SmartFace Integration’s github.

• Python - If you are interested in a sample for the python programming language, please take a look at the PythonGraphQLSubscription script
• C# - If you are interested in a sample for the C$ programming language, please take a look at the BirdWatch application or the GraphQLClient