Getting Started

Getting Started

The SwissMentor API is based on GraphQL technology. It allows easy and powerful data retrieval and mutation. As the SwissMentor web portal uses the SwissMentor GraphQL API itself, all the power used internally is also available for external users.

Deprecated APIs

Outdated REST and SOAP APIs are still available on the servers. However, we strongly recommend using the new SwissMentor GraphQL API.

Connect to the GraphQL Playground

The best way to try and experiment with the SwissMentor API is to use the GraphQL Sandbox web interface.

Navigate in your Web Browser to the Apollo GraphQL Sandbox at https://studio.apollographql.com/sandbox/explorer.

You should see an interface like:

On the top left, enter the GraphQL URL to your desired Server:

If successful, the dot should be green and the available queries should be loaded:

Run your first query

Execute your first query. This query shows the current SwissMentor version number and your customer code. As the information is public, no authentication is needed to run this query.

query {
  systemInfo {
    serverVersion
    customerCode
  }
}

You should get a result like:

{
  "data": {
    "systemInfo": {
      "serverVersion": "00.0000.00.0",
      "customerCode": "UNK"
    }
  }
}

Run the query in curl

The same query can be executed in the command line using the curl tool:

curl -X POST -H "Content-Type: application/json" \
  --data '{ "query": "query { systemInfo { serverVersion customerCode } }" }' \
  https://your.server/graphql

Queries with no variables can also use the simpler application/graphql query mode:

curl -X POST -H "Content-Type: application/graphql" \
  --data 'query { systemInfo { serverVersion customerCode } }' \
  https://your.server/graphql

Run the query in PowerShell

The same query can be executed using PowerShell:

$url = "https://your.server/graphql"

$body = @'
{ "query": "query { systemInfo { serverVersion customerCode } }" }
'@

$headers = @{
  "content-type" = "application/json"
  # "Authorization" = "bearer tokenCode"
}

Invoke-WebRequest -Uri $url -Method POST -Body $body -Headers $headers

GraphQL Advantages

Why GraphQL?

• Single Endpoint: One URL for all API operations
• Strong Type System: Self-documenting with introspection
• Flexible Queries: Get exactly the data you need
• Real-time: Built-in subscription support
• Versioning: No API versioning needed

GraphQL vs REST

Feature	GraphQL	REST
Endpoints	Single endpoint	Multiple endpoints
Data Fetching	Precise data selection	Fixed data structure
Over/Under-fetching	No over/under-fetching	Common problem
Documentation	Self-documenting	Manual documentation

API Structure

The SwissMentor GraphQL API is organized around these main concepts:

Core Objects

• Objects: Base entities (Persons, Courses, Documents, etc.)
• Links: Relationships between objects
• Categories: Tagging and classification system
• Memberships: Time-bound relationships

Operations

• Queries: Read data from the system
• Mutations: Modify data in the system
• Subscriptions: Real-time updates (where available)

Common Patterns

Object Queries

Most objects follow a similar pattern:

query {
  object(id: "123") {
    id
    name
    objectType
    # ... other fields
  }
}

List Queries

Lists support filtering and pagination:

query {
  objects(filter: { objectType: "Person" }, first: 10) {
    nodes {
      id
      name
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Mutations

Modifications follow a consistent pattern:

mutation {
  updatePerson(id: "123", person: { name: "New Name" }) {
    id
    name
  }
}

Next Steps

1. Authentication - Learn how to authenticate with the API
2. Persons API - Work with person data

Weitere API-Dokumentation (Gruppen, Kurse, etc.) folgt in Kürze.

Development Tools

Recommended Tools

• Apollo GraphQL Sandbox - Web-based GraphQL IDE
• GraphiQL - Alternative GraphQL IDE
• Postman - REST client with GraphQL support
• Insomnia - API client with GraphQL support

Client Libraries

• JavaScript/TypeScript: Apollo Client, urql, graphql-request
• Python: gql, graphene
• C#: GraphQL.Client, Hot Chocolate
• Java: GraphQL Java Tools

Support and Resources

• Schema Documentation: Available through GraphQL introspection
• Examples: See individual endpoint documentation
• Support: Contact SwissMentor support team
• Updates: Check the changelog for API updates