Writing APIs Without Servant vs. Using Servant

Writing APIs Without Servant vs. Using Servant

When developing web APIs in Haskell, there are various approaches to consider. Below is a comparison of how APIs would be written without using Servant versus how Servant simplifies and enhances the process.

Writing APIs Without Servant

1. Manual Routing and Handling:

   • Without Servant, developers would need to manually define routes and handlers for each endpoint in their application. This often involves writing boilerplate code to parse requests, validate inputs, and format responses.
   • Example:

    handleGetUser :: Request -> Response
    handleGetUser req = 
        let userId = extractUserId req
            user = fetchUserFromDatabase userId
        in toJSONResponse user
   

2. Error Handling:

   • Error handling would need to be implemented manually for each endpoint, leading to potential inconsistencies across the API.
   • Developers would have to ensure that all endpoints return appropriate HTTP status codes and error messages.

3. Serialization/Deserialization:

   • Developers would need to manually handle the conversion between data types and JSON (or other formats) for each request and response.
   • This can lead to repetitive code and increased chances of errors if the structure of data changes.

4. Lack of Type Safety:

   • Without a type-safe framework like Servant, there is a higher risk of runtime errors due to mismatched data types or unexpected input formats.
   • Developers may not have compile-time guarantees that their API implementation matches the intended design.

How Servant Helps

1. Type-Safe API Definition:

   • Servant allows developers to define their API using Haskell types, ensuring that the implementation adheres to the specified structure.
   • Example:

    type UsersAPI = "users" :> Capture "id" Int :> Get '[JSON] User
   

2. Automatic Routing:

   • Servant automatically handles routing based on the defined API types, reducing boilerplate code and simplifying request handling.
   • The framework generates handlers for each endpoint based on the type definitions, allowing developers to focus on business logic.

3. Built-in Serialization/Deserialization:

   • Servant provides automatic serialization and deserialization of request and response bodies based on the defined types.
   • This eliminates repetitive code and ensures that data is consistently formatted across the API.

4. Comprehensive Error Handling:

   • With Servant, error handling can be standardized across all endpoints, making it easier to manage responses for different scenarios.
   • The framework can generate appropriate HTTP status codes based on the results of handler functions.

5. Compile-Time Guarantees:

   • By leveraging Haskell's strong type system, Servant provides compile-time checks that ensure the API implementation matches its definition.
   • This significantly reduces runtime errors and improves overall reliability.

Conclusion

Writing APIs without Servant involves more manual effort in defining routes, handling requests, managing serialization, and ensuring type safety. This can lead to increased complexity and potential errors in the codebase. In contrast, Servant streamlines the process by providing a type-safe DSL for defining APIs, automating routing and serialization, and enforcing compile-time checks. As a result, developers can create robust web APIs more efficiently while maintaining high standards of reliability and maintainability.

Citations:
[1] https://byteally.github.io/webapi/
[2] https://hackage.haskell.org/package/api-tools-0.10.1.0/docs/Data-API-Tutorial.html
[3] https://dev.to/fabianveal/building-a-rest-api-with-haskell-2d54
[4] https://github.com/cackharot/haskell-web-api-template
[5] https://byteally.com/insights/haskell-development/writing-a-haskell-client-for-a-third-party-api/
[6] https://vadosware.io/post/rest-ish-services-in-haskell-part-4/
[7] https://lettier.github.io/posts/2016-07-15-building-a-haskell-web-api.html
[8] https://taylor.fausak.me/2014/10/21/building-a-json-rest-api-in-haskell/
[9] https://stackoverflow.com/questions/51367527/is-it-possible-to-build-a-restful-api-in-haskell-without-using-reader-writer-sta