APIContract

English | 日本語

Define an HTTP API once in Swift, and let the client and the server share it — endpoints, parameters and errors are checked by the compiler on both sides.

Overview

An endpoint is a struct. Its properties are the request, its Output is the response, and macros generate everything in between: URL building, query encoding, body encoding, and the server-side decoding that turns a raw request back into the same struct.

• @APIGroup / @Endpoint describe the API declaratively
• @PathParam, @QueryParam, @Body, @Header place each value in the request
• @StreamingEndpoint covers Server-Sent Events
• No transport is bundled: you supply the client, so URLSession or anything else works

Usage

import APIContract

@APIGroup(path: "/v1/users", auth: .bearer)
enum UsersAPI {
    @Endpoint(.get, path: ":userId")
    struct Get {
        @PathParam var userId: String
        typealias Output = User
    }
}

let user = try await UsersAPI.Get(userId: "123").execute(using: client)

Documentation

API reference and guides — defining endpoints, implementing a client, and serving the same definitions.

Requirements

Swift 6.2+ · iOS 17+ / macOS 14+ / tvOS 17+ / watchOS 10+ · Linux

Installation

dependencies: [
    .package(url: "https://github.com/no-problem-dev/swift-api-contract.git", from: "2.0.0")
]

.target(
    name: "YourTarget",
    dependencies: [
        .product(name: "APIContract", package: "swift-api-contract")
    ]
)

Contributing

See CONTRIBUTING.md.

License

MIT License — see LICENSE.