API Expert | Bootspring Docs

The API Expert agent specializes in API design, documentation, and best practices for building robust APIs.

Expertise Areas#

REST API Design - Resources, methods, status codes
GraphQL - Schemas, resolvers, subscriptions
tRPC - Type-safe APIs, procedures
OpenAPI/Swagger - Documentation, code generation
Versioning - Strategies, deprecation, migration
Rate Limiting - Throttling, quotas, fairness
Error Handling - Standard errors, problem details

Usage Examples#

API Design#

Use the api-expert agent to design a RESTful API for a task management application.

Response includes:

Resource design
Endpoint definitions
Request/response schemas
Authentication strategy

GraphQL Schema#

Use the api-expert agent to create a GraphQL schema for an e-commerce platform.

Response includes:

Type definitions
Query and mutation definitions
Subscription setup
Resolver patterns

API Documentation#

Use the api-expert agent to generate OpenAPI documentation for our existing API.

Response includes:

OpenAPI specification
Endpoint documentation
Schema definitions
Example requests/responses

REST API Best Practices#

Resource Naming#

Good:
GET    /users              # List users
GET    /users/:id          # Get user
POST   /users              # Create user
PUT    /users/:id          # Update user
DELETE /users/:id          # Delete user
GET    /users/:id/orders   # Get user's orders

Bad:
GET    /getUsers           # Verb in URL
POST   /createUser         # Verb in URL
GET    /user/:id           # Inconsistent plural
DELETE /users/:id/delete   # Redundant verb

HTTP Status Codes#

Code	Meaning	Use Case
200	OK	Successful GET, PUT
201	Created	Successful POST
204	No Content	Successful DELETE
400	Bad Request	Validation error
401	Unauthorized	Missing/invalid auth
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist
409	Conflict	Duplicate resource
422	Unprocessable	Business logic error
429	Too Many Requests	Rate limited
500	Server Error	Unexpected error

Response Structure#

// Success response
{
  "data": {
    "id": "123",
    "name": "John Doe",
    "email": "john@example.com"
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

// List response with pagination
{
  "data": [
    { "id": "1", "name": "Item 1" },
    { "id": "2", "name": "Item 2" }
  ],
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 100,
    "totalPages": 5
  },
  "links": {
    "self": "/items?page=1",
    "next": "/items?page=2",
    "last": "/items?page=5"
  }
}

// Error response (RFC 7807)
{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation Error",
  "status": 400,
  "detail": "The request body contains invalid data",
  "instance": "/users",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

GraphQL Patterns#

Schema Design#

type Query {
  user(id: ID!): User
  users(filter: UserFilter, pagination: PaginationInput): UserConnection!
}

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
  deleteUser(id: ID!): DeleteUserPayload!
}

type User {
  id: ID!
  email: String!
  name: String
  posts(first: Int, after: String): PostConnection!
  createdAt: DateTime!
}

type UserConnection {
  edges: [UserEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type UserEdge {
  node: User!
  cursor: String!
}

input UserFilter {
  search: String
  status: UserStatus
}

input CreateUserInput {
  email: String!
  name: String
  password: String!
}

type CreateUserPayload {
  user: User
  errors: [Error!]
}

Resolver Patterns#

const resolvers = {
  Query: {
    user: (_, { id }, context) => {
      return context.dataSources.users.findById(id);
    },
    users: async (_, { filter, pagination }, context) => {
      return context.dataSources.users.findMany({
        ...filter,
        ...pagination,
      });
    },
  },

  User: {
    // Field-level resolver with DataLoader
    posts: (user, args, context) => {
      return context.loaders.postsByUser.load(user.id);
    },
  },

  Mutation: {
    createUser: async (_, { input }, context) => {
      try {
        const user = await context.dataSources.users.create(input);
        return { user, errors: null };
      } catch (error) {
        return { user: null, errors: [formatError(error)] };
      }
    },
  },
};

tRPC Patterns#

import { initTRPC } from '@trpc/server';
import { z } from 'zod';

const t = initTRPC.context<Context>().create();

export const appRouter = t.router({
  user: t.router({
    list: t.procedure
      .input(z.object({
        page: z.number().default(1),
        perPage: z.number().default(20),
      }))
      .query(async ({ input, ctx }) => {
        return ctx.prisma.user.findMany({
          skip: (input.page - 1) * input.perPage,
          take: input.perPage,
        });
      }),

    create: t.procedure
      .input(z.object({
        email: z.string().email(),
        name: z.string().optional(),
      }))
      .mutation(async ({ input, ctx }) => {
        return ctx.prisma.user.create({ data: input });
      }),
  }),
});

API Versioning#

// URL versioning
app.use('/api/v1', v1Router);
app.use('/api/v2', v2Router);

// Header versioning
app.use((req, res, next) => {
  const version = req.headers['api-version'] || 'v1';
  req.apiVersion = version;
  next();
});

// Deprecation headers
res.set('Deprecation', 'true');
res.set('Sunset', 'Sat, 31 Dec 2024 23:59:59 GMT');
res.set('Link', '</api/v2/users>; rel="successor-version"');

Sample Prompts#

Task	Prompt
Design	"Design a REST API for a booking system"
GraphQL	"Convert this REST API to GraphQL"
Documentation	"Generate OpenAPI spec from this Express app"
Versioning	"Plan API versioning strategy with deprecation"
Errors	"Implement RFC 7807 error responses"

Configuration#

// bootspring.config.js
module.exports = {
  agents: {
    customInstructions: {
      'api-expert': `
        - Follow REST best practices
        - Use appropriate HTTP status codes
        - Include comprehensive documentation
        - Plan for versioning
        - Consider rate limiting
      `,
    },
  },
  skills: {
    preferred: {
      api: 'rest', // or 'graphql', 'trpc'
    },
  },
};

Backend Expert - Server implementation
Security Expert - API security
Software Architect - API architecture