Papyrus: Turn your HTTP APIs into Swift Protocols

Community Showcase
1

Hey Folks!

I know there have been a few recent posts of macro based networking libraries, but I’d like to show everyone Papyrus: a Swift library that turns your HTTP APIs into Swift Protocols.

With Papyrus, you'll use macros to define your API's endpoints, request content, response types, and typical logic like authentication, default key case mapping, and decoding responses all in lightweight, easy to read protocols.

Your network layer will be clean, require less boilerplate, and be easier to mock when testing.

Here’s an example of an API defined with Papyrus:

@API
@Authentication(.bearer("<api-key>"))
@KeyMapping(.snakeCase)
protocol Transactions {
    @GET("/transactions")
    func getTransactions() async throws -> [Transaction]

    @GET("/transactions/:id")
    func getTransaction() async throws -> Transaction

    @URLForm
    @POST("/transactions")
    func createTransaction(name: String, price: Double) async throws
}

Once defined, Papyrus automatically generates an TransactionsAPI type which you can use to call the endpoints using a configurable Provider that's powered by Alamofire.

let provider = Provider(baseURL: "https://api.project.com/")
let transactions: Transactions = TransactionsAPI(provider: provider)
let myTransactions = try await transactions.getTransactions()

You can use both Swift Concurrency APIs or completion based APIs if you haven’t migrated your project to concurrency yet.

@API
protocol Users {
    @GET("/users")
    func getUser(completionHandler: @escaping (Result<User, Error>) -> Void)
}

For my fellow Linux / Swift on the Server fans there's a lightweight, AsyncHTTPClient based driver that you can use in lieu of the default Alamofire one. The ability to provide endpoints via NIO based servers like Vapor, Hummingbird, or (shameless plug) Alchemy is coming soon :eyes:

Other bells & whistles Papyrus has to offer are:

  • JSON and URLForm encoding
  • Automatic key mapping (i.e. camelCase -> snake_case)
  • Custom Provider Interceptors & Builders
  • Custom Alamofire Sessions
  • Generated mock APIs for easy testing
  • Accessing raw Request / Response types
  • Endpoint or API wide headers, queries, and body fields.

:wave: Thanks for looking - would love to get your feedback!

You can check Papyrus out here:

5 Likes