api_kit library
Production-ready REST API framework with comprehensive JWT authentication system.
🚀 v0.0.5+ Features - NOW AOT COMPATIBLE!
- ⚡ Hybrid routing system - Generated code (AOT) + Mirrors fallback (JIT)
- 🔐 Complete JWT validation with @JWTPublic, @JWTController, @JWTEndpoint annotations
- 🎯 Custom validators extending JWTValidatorBase with AND/OR logic
- 🚫 Token blacklisting and management system
- 📝 Annotation-based routing with @Controller, @GET, @POST, etc.
- 🛡️ Enterprise-grade security headers and middleware pipeline
- 🧪 140+ tests passing - production ready
- 📦 AOT compilation support with code generation
Migration Path
- Existing code works unchanged (static analysis)
- Run
dart run build_runner buildfor AOT compatibility - Zero breaking changes from previous versions
Perfect for MVPs, rapid prototyping, and enterprise applications.
Classes
- AnnotationAPI
- Simple API to detect annotations
- AnnotationData
- Base class for typed annotation data
- AnnotationDetails
- Class that contains all the data of a found annotation
- AnnotationResult
- Class that gets all the data and units of the annotations.
-
ApiErr<
E> - Represents a detailed error originating from an API interaction.
- ApiKit
- Standardized API result handling using result_controller. This replaces the old ApiResponse pattern with proper Ok/Err semantics.
- ApiResponseBuilder
- Response builder for converting ApiResult to HTTP responses. Use this to convert your business logic results into HTTP responses.
-
ApiResult<
T> - ApiResult: A specialized Result type for HTTP API operations
- ApiServer
- API server with auto-discovery and fluent configuration. Supports automatic controller registration without manual controllerList
- BaseController
- Base class for all API controllers with common functionality.
- BuiltInMiddleware
- Built-in middleware creators for common use cases.
- ControllerRegistry
- Auto-discovery registry for controllers using static analysis Replaces manual controller registration with automatic detection
- CorsConfig
- CORS configuration.
- Delete
- Annotation for DELETE endpoints
- DeleteData
- Specific data for @Delete
- EnhancedAuthMiddleware
- Enhanced JWT authentication middleware
- GenericAnnotationData
- Generic data for non-specific annotations
- Get
- Annotation for GET endpoints
- GetData
- Specific data for @Get
- JWTController
- Annotation for controller-level validation
- JWTEndpoint
- Annotation for specific endpoint-level validation
- JWTPublic
- Annotation to mark an endpoint as public (without JWT validation)
- JWTValidatorBase
- Base abstract class for all custom JWT validators.
- MethodDispatcher
- Method dispatcher registry for AOT compatibility
- MiddlewareRegistry
- Registry for custom middleware that can be applied to specific endpoints.
- MyAdminValidator
- Validator for admin users Verifies role, active status, and admin permissions
- MyBusinessHoursValidator
- Validator for business hours Verifies that access occurs within allowed hours
- MyDepartmentValidator
- Validator for specific departments Allows configuring allowed departments and required level
- MyFinancialValidator
- Validator for financial operations Allows configuring specific requirements such as minimum amounts
- Param
- Annotation for general parameters
- ParamData
- Specific data for @Param
- Patch
- Annotation for PATCH endpoints
- PatchData
- Specific data for @Patch
- PathParam
- Annotation for path parameters (/users/{id})
- PathParamData
- Specific data for @PathParam
- Post
- Annotation for POST endpoints
- PostData
- Specific data for @Post
- Put
- Annotation for PUT endpoints
- PutData
- Specific data for @Put
- QueryParam
- Annotation for query parameters (?page=1&size=10)
- QueryParamData
- Specific data for @QueryParam
- RateLimitConfig
- Rate limiting configuration.
- RateLimiter
- Rate limiter implementation for API protection.
- Repository
- Annotation for repositories
- RepositoryData
- Specific data for @Repository
- Request
- An HTTP request to be processed by a Shelf application.
- RequestBody
- Annotation for the request body
- RequestBodyData
- Specific data for @RequestBody
- RequestContext
- Annotation for the request context
- RequestHeader
- Annotation for HTTP headers
- RequestHeaderData
- Specific data for @RequestHeader
- RequestHost
- Annotation for the request host
- RequestMethod
- Annotation for the HTTP method (GET, POST, PUT, etc.)
- RequestPath
- Annotation for the request path
- RequestPort
- Annotation for the request port
- RequestScheme
- Annotation for the request scheme (http/https)
- RequestUrl
- Annotation for the full request URL
- Response
-
The response returned by a
Handler. - RestController
- Annotation to mark classes as REST controllers
- RestControllerData
- Specific data for @RestController
- RouteInfo
- Route information for registration
- RouterBuilder
- Builds routes automatically from controller annotations.
- ServerConfig
- Main server configuration.
- Service
- Annotation for service components
- ServiceData
- Specific data for @Service
- StaticRouterBuilder
- Static Router Builder - AOT Compatible, No Mirrors
- ValidationResult
- Validation result using the Result Pattern
Enums
Extensions
- AnnotationResultExtensions on AnnotationResult
- Extensions to facilitate use
- ControllerRegistration on BaseController
- Base class extension to help controllers register their methods
Functions
-
corsMiddleware(
CorsConfig config) → Middleware - Creates CORS middleware.
-
errorHandlingMiddleware(
) → Middleware - Creates error handling middleware.
-
loggingMiddleware(
) → Middleware - Creates logging middleware.
-
rateLimitMiddleware(
RateLimitConfig config) → Middleware - Creates rate limiting middleware.
-
requestIdMiddleware(
) → Middleware - Creates request ID middleware for tracing.
-
requestSizeLimitMiddleware(
int maxBytes) → Middleware - Creates request size limit middleware.
-
securityHeadersMiddleware(
) → Middleware - Creates security headers middleware (OWASP protection).
Typedefs
-
MethodHandler
= Future<
Response> Function(Request request) - Method handler function type