6/8 - Public Beta (Discord)|See Changelog
Skip to main content

OpenLift GraphQL API

Welcome to the OpenLift GraphQL API documentation. This API provides comprehensive access to all OpenLift features through a modern GraphQL interface optimized for Flutter mobile applications.

🚀 Getting Started​

The OpenLift API is built with GraphQL, providing:

  • Type-safe queries with strong typing
  • Efficient data fetching - request only what you need
  • Real-time capabilities through subscriptions
  • Comprehensive documentation via introspection

📋 Available APIs​

Core Data APIs​

Coming Soon​

  • Programs - Access training programs and plans
  • Progress - Track performance analytics and photos
  • Users - User management and authentication

🔧 Quick Setup​

1. Add GraphQL Dependencies​

pubspec.yaml
dependencies:
  graphql_flutter: ^5.1.2
  # Optional: for code generation
  graphql_codegen: ^0.13.0

2. Configure GraphQL Client​

lib/graphql_client.dart
import 'package:graphql_flutter/graphql_flutter.dart';

class GraphQLConfig {
  static HttpLink httpLink = HttpLink(
    'https://your-openlift-instance.com/graphql',
  );

  static AuthLink authLink = AuthLink(
    getToken: () async => 'Bearer your-jwt-token',
  );

  static Link link = authLink.concat(httpLink);

  static GraphQLClient client = GraphQLClient(
    link: link,
    cache: GraphQLCache(store: HiveStore()),
  );
}

3. Initialize in Your App​

lib/main.dart
import 'package:flutter/material.dart';
import 'package:graphql_flutter/graphql_flutter.dart';

void main() async {
  await initHiveForFlutter();
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return GraphQLProvider(
      client: ValueNotifier(GraphQLConfig.client),
      child: MaterialApp(
        title: 'OpenLift App',
        home: HomeScreen(),
      ),
    );
  }
}

🔐 Authentication​

OpenLift uses JWT (JSON Web Tokens) for authentication. Include the token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Getting a Token​

// Example login mutation (implementation depends on your auth setup)
const String loginMutation = '''
  mutation Login(\$email: String!, \$password: String!) {
    login(email: \$email, password: \$password) {
      token
      user {
        id
        email
        name
      }
    }
  }
''';

📊 GraphQL Schema​

Introspection​

You can explore the full schema using introspection:

const String introspectionQuery = '''
  query IntrospectionQuery {
    __schema {
      queryType { name }
      mutationType { name }
      subscriptionType { name }
      types {
        ...FullType
      }
    }
  }
  
  fragment FullType on __Type {
    kind
    name
    description
    fields {
      name
      type { ...TypeRef }
    }
  }
  
  fragment TypeRef on __Type {
    kind
    name
  }
''';

Common Patterns​

Pagination​

OpenLift uses Relay-style cursor-based pagination:

type Query {
  exercises(
    first: Int
    after: String
    search: String
  ): ExerciseConnection
}

type ExerciseConnection {
  totalCount: Int!
  pageInfo: PageInfo!
  edges: [ExerciseEdge!]!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

Error Handling​

GraphQL errors follow this structure:

{
  "errors": [
    {
      "message": "Exercise not found",
      "locations": [{"line": 2, "column": 3}],
      "path": ["exercise"],
      "extensions": {
        "code": "NOT_FOUND"
      }
    }
  ]
}

🎯 Best Practices​

1. Query Optimization​

  • Request only the fields you need
  • Use fragments for reusable field sets
  • Implement proper loading states

2. Caching Strategy​

  • Use FetchPolicy.cacheFirst for static data
  • Implement cache normalization
  • Clear cache when user logs out

3. Error Handling​

  • Handle both GraphQL and network errors
  • Provide meaningful error messages to users
  • Implement retry mechanisms

4. Performance​

  • Batch queries when possible
  • Use connection pooling
  • Implement pagination for large datasets

🧪 Testing​

Mock GraphQL Client​

import 'package:mockito/mockito.dart';
import 'package:graphql_flutter/graphql_flutter.dart';

class MockGraphQLClient extends Mock implements GraphQLClient {}

void main() {
  group('Exercise Service', () {
    late MockGraphQLClient mockClient;
    late ExerciseService service;

    setUp(() {
      mockClient = MockGraphQLClient();
      service = ExerciseService(mockClient);
    });

    test('should fetch exercise by id', () async {
      // Test implementation
    });
  });
}

🔄 Rate Limiting​

The API implements rate limiting to ensure fair usage:

  • Authenticated requests: 1000 requests per hour
  • Public queries: 100 requests per hour

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

📚 Additional Resources​

🆘 Support​

Need help with the API?

  1. Check the individual API documentation for detailed examples
  2. Use GraphQL introspection to explore the schema
  3. Contact support for implementation questions

Ready to start building? Check out the Exercise API to begin integrating with OpenLift's exercise database.