Getting Started

What is GraphQL

GraphQL is an API query language.

It lets the client ask exactly for the data it needs.
No more. No less.

Main ideas:

One endpoint.
Client chooses fields.
Strong types.
Clear schema.

GraphQL replaces many REST endpoints with one structured API.

What We Use in Finmars

In Finmars, GraphQL is built with:

Django
Strawberry GraphQL https://github.com/strawberry-graphql/strawberry

Strawberry is a Python GraphQL library.
It works well with Django models.
It uses Python type hints to define the schema.

Key points:

Schema is written in Python.
Types are strict.
Queries are validated before execution.
Errors are clear.

GraphQL Endpoint

Finmars exposes GraphQL via a single endpoint.

:realm_code:/:space_code:/graphql/

This endpoint supports:

Queries
Mutations
Schema introspection

How to Access the Endpoint

From Browser (Playground)

Open the GraphQL playground in your browser:

https://<your-finmars-domain>/:realm_code:/space_code:/graphql/

E.g. https://eu-central.finmars.com/realm0v4ry/space063sw/graphql/ (Link is not lead to anything, just an example)

You will see:

Query editor
Schema explorer
Result panel

You must be authenticated.

Authentication

GraphQL uses the same authentication as the REST API.

Usually:

Keycloak Auth Token (web)
Authorization header (JWT tokens)

"DEFAULT_AUTHENTICATION_CLASSES": (   
   "poms.common.authentication.JWTAuthentication",    
   "poms.common.authentication.KeycloakAuthentication",
),

If you are not authenticated:

Requests will fail
Data will not be returned

From Code

Send a POST request to /graphql/.

Content type:

application/json

Body example:

Headers must include authentication.