Authentication and API Requests

This document provides information on how to authenticate with the Huskycare API and how to make API requests.

Authentication

The Huskycare API uses OAuth2 for authentication. There are two main authentication flows:

1. UI-based Authentication: Used for web interfaces like GraphiQL
2. API Authentication: Used for programmatic access to the API

UI-based Authentication

When accessing developer tools like GraphiQL, the system uses OAuth2 Login flow:

1. Navigate to the GraphiQL interface (typically at /graphiql)
2. You will be redirected to the OAuth2 login page
3. Enter your credentials
4. After successful authentication, you will be redirected back to the GraphiQL interface

API Authentication

For programmatic access to the API, you need to:

1. Obtain a JWT token from the OAuth2 authorization server
2. Include this token in your API requests

Obtaining a JWT Token

To obtain a JWT token:

1. Make a POST request to the OAuth2 token endpoint with your client credentials
2. Example request:

curl -X POST \
  https://[auth-server-url]/oauth2/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET'

3. The response will include an access_token which is your JWT token

Using the JWT Token

Include the JWT token in the Authorization header of your API requests:

Authorization: Bearer YOUR_JWT_TOKEN

Making API Requests

The Huskycare API uses GraphQL for API requests. All GraphQL requests are made to the /graphql endpoint.

GraphQL Basics

GraphQL allows you to request exactly the data you need. A GraphQL request consists of:

1. Operation Type: Query (read data), Mutation (write data), or Subscription (real-time updates)
2. Operation Name: A name for your operation (optional but recommended)
3. Variables: Input values for your operation (optional)
4. Selection Set: The fields you want to retrieve

Available API Operations

The Huskycare API provides various operations for different domains. Here are some examples:

Tour Management

• Query active tours: Retrieve active tours based on filters like date
• Query target tours: Retrieve target tours based on filters
• Query a specific tour: Retrieve details of a specific tour by ID
• Add empty tour: Create a new empty tour
• Add tour entry: Add an entry to a tour
• Take work item: Assign a work item to a user

Client Management

• Query clients: Retrieve clients based on filters
• Query a specific client: Retrieve details of a specific client by ID
• Create client: Create a new client with personal data
• Update client: Update client information
• Add client contact person: Add a contact person to a client

Making API Requests with curl

Here's how to make a GraphQL request using curl:

curl -X POST \
  https://[api-url]/graphql \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -d '{
    "query": "query { /* Your GraphQL query here */ }",
    "variables": {}
  }'

Making API Requests with a GraphQL Client

You can also use GraphQL clients like Apollo Client, urql, or graphql-request to make API requests. Here's an example using graphql-request:

import {request} from 'graphql-request';

const query = `
  query {
    // Your GraphQL query here
  }
`;

const headers = {
    Authorization: 'Bearer YOUR_JWT_TOKEN',
};

request('https://[api-url]/graphql', query, {}, headers)
    .then((data) => console.log(data))
    .catch((error) => console.error(error));

Error Handling

GraphQL responses include an errors array when there are errors. Always check for this array in your responses.

Example error response:

{
  "errors": [
    {
      "message": "Not authorized to access this resource",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "resourceName"
      ]
    }
  ],
  "data": null
}

Rate Limiting

The API implements rate limiting to prevent abuse. If you exceed the rate limit, you'll receive a 429 Too Many Requests response. Implement appropriate backoff strategies in your clients.

Best Practices

1. Request only what you need: GraphQL allows you to specify exactly which fields you want, reducing payload size
2. Use meaningful operation names: This helps with debugging and monitoring
3. Handle errors gracefully: Always check for errors in the response
4. Implement token refresh: JWT tokens expire, so implement a refresh mechanism
5. Use variables for dynamic values: This helps prevent injection attacks
6. Explore the API using GraphiQL: Use the GraphiQL interface to explore the API schema and test queries
7. Check the schema documentation: The GraphiQL interface provides documentation on the available types and operations

Exploring the API

To explore the full API schema and available operations:

1. Authenticate to the GraphiQL interface at /graphiql
2. Use the Documentation Explorer panel (usually on the right side) to browse the schema
3. The schema is divided into domains like Tour, Client, Billing, etc.
4. Each domain has its own queries and mutations
5. You can see the required input types and return types for each operation

Alternatively, you can use our GraphQL API Documentation which provides an interactive schema explorer that allows you to browse the entire API schema without needing to authenticate.

This will help you understand what operations are available and how to structure your requests.