App API Reference (Consumer)

Introduction

The App context provides APIs for integrating with and extending applications built on the AWorld platform. These APIs are designed for use in end-user applications and client-side interfaces.

Authentication

The App context uses the common authentication mechanisms described in Common Features.

M2M Implementation Details

For App context APIs that require "user level" access in machine-to-machine (M2M) flows, you must include the userId of the user to impersonate in a header with every call:

x-user-id: USER_ID_TO_IMPERSONATE

This allows your service to perform actions on behalf of specific users while using client credentials for authentication.

API Endpoints

GraphQL API

The primary API for the App context is a GraphQL API:

Current Endpoint: https://v1.gql.app.aworld.cloud/graphql

Note: These endpoints are currently exposing internal APIs directly to customers. In the future, all APIs will be accessible through a single reverse proxy, and these endpoints will change.

API Versioning

GraphQL: GraphQL APIs typically use a rolling updates approach without formal versioning until breaking changes occurs. This allows the API to evolve while maintaining backward compatibility. During this pre-alpha stage, more significant changes may occur, but once stable, changes will follow the rolling approach.

REST: REST APIs (when published) will use explicit versioning (e.g., v1, v2). The version numbers will be aligned with GraphQL whenever REST requires updates.

REST APIs

REST APIs will have feature parity with GraphQL APIs but are not published yet:

Future Base URL: To be determined after reverse proxy implementation

GraphQL Schema

The App context GraphQL API provides the following main types of operations:

Queries: For retrieving data

Mutations: For creating, updating, or deleting data

User Context

When authenticated, your API requests operate within the context of:

The authenticated User

The Workspace associated with the user

The Account associated with the workspace

GraphQL Schema Details

The App context GraphQL API includes the following components:

Scalar Types

AWSDateTime, AWSDate, AWSTime, AWSTimestamp

AWSEmail, AWSJSON, AWSURL, AWSPhone, AWSIPAddress

Long

Interfaces

Node: Base interface with creation and update timestamps

Connection: Interface for paginated collections of items

Enums

QuizDifficulty: EASY, MEDIUM, HARD

QuizAnswer: opt1, opt2, opt3, opt4

QuizOrigin: CATALOG, CUSTOM

QuizPlacement: STANDALONE, STORY, NEWS

QuizOutcome: SUCCESS, FAIL

Types

Quiz: Represents a quiz with its properties

QuizConnection: Paginated collection of quizzes

QuizTranslation: Translations for a quiz (questions, options, explanations)

QuizLog: Record of a quiz attempt by a user

Available Mutations

Submit Quiz

Submit a user's answer to a quiz:

Example variables:

{
  "input": {
    "quizId": "quiz-123",
    "answer": "opt2",
    "context": "default"
  }
}

API Features

The App context implements the common API features described in Common API Features. Please refer to that document for detailed information about:

For the App context, idempotency is particularly important when creating or updating user data. For example, if you attempt to create the same user twice with concurrent requests or within the 5-minute idempotency window, only the first API call would succeed. Other calls would return the same payload with the added idempotency header.

Pagination

The App context follows the standard pagination approach described in Common API Features.

For App-specific resources, the pagination pattern is implemented as follows:

Example query for listing quizzes with pagination:

With input structure:

For pagination guidelines and best practices, refer to the Common API Features documentation.

Rate Limiting

Please refer to the Common API Features documentation for information about rate limiting.

Example Integration

Here's an example of integrating with the App context API in a JavaScript application to submit a quiz answer:

Additional Resources

GraphQL Documentation

App Context Schema Explorer (requires authentication)

API Changelog (requires authentication)

Consumer/App API Reference

Introduction#

Authentication#

M2M Implementation Details#

API Endpoints#

GraphQL API#

API Versioning#

REST APIs#

GraphQL Schema#

User Context#

GraphQL Schema Details#

Scalar Types#

Interfaces#

Enums#

Types#

Available Mutations#

Submit Quiz#

API Features#

Pagination#

Rate Limiting#

Example Integration#

Additional Resources#