RFC7807 — Problem Details for HTTP APIs style response messages.

This module defines Rfc7807Error data type that represents RFC7807 style response message along with few extensions that are not defined by the standard, but allowed by it.

The sandard specifies two serialisation formats:

1. JSON (application/problem+json) and
2. XML (application/problem+xml)

This package supports only JSON serialisation, but it should not be hard to build XML serialisation yourself, if required. We also expose few low-level definitions for cases when you want to build your own JSON serialisation that is compatible with the standard. If you're interested in that then best to look at Usage Examples and Encoding and Decoding sections.

This package also provides Servant integration that is defined in a separate module Servant.Server.RFC7807.

If you want to jump straight to using this then go directly to Usage Examples section.

Definitions in this section are useful for defining your own JSON encoding/decoding. See Usage Examples section for ideas on how to use them.

What's provided in here are:

• Function toKeyValue for generic serialisation of Rfc7807Error into JSON object representation.
• Function parseObject for parsing JSON Object (key-value map) into Rfc7807Error.
• Parameters that modify behaviour of toKeyValue and 'parseObject: EncodingOptions, defaultEncodingOptions, and ExtensionField.

We start with a simple use case in Type Alias section and we get progressively more complicated. Which one is best for you depends on many factors. There's a little guidance that we can give you in that regard, but maybe consider following:

• If you are just exploring or evaluating multiple options then maybe start with the simple example first.
• If you want to integrate RFC7807 style messages into existing system, while requiring backward compatibility, then go with the more complicated example. It will allow you to merge existing error responses with RFC7807 style ones more easily.

Haskell/GHC language extensions being used in the examples:

• RecordWildCards and NamedFieldPuns — please read this great article if you're not familiar with these extensions: The Power of RecordWildCards by Dmitrii Kovanikov.
• LambdaCase — allows us to use \case as a short hand for \x -> case x of. See GHC User's Guide — Lambda-case for more information.
• OverloadedStrings — allows us to define string literals for types like Text without needing to manually pack/convert String values. See GHC User's Guide — Overloaded string literals for more information.

The easiest way how to use Rfc7807Error data type without always needing to pass all the type arguments is by creating a type alias like this:

type ErrorResponse = Rfc7807Error ErrorType () ()

data ErrorType
    = DocumentNotFound
    {- ... -}

instance ToJSON ErrorType where
    toJSON = \case
        DocumentNotFound ->
            String "https://example.com/docs/error#document-not-found"
        {- ... -}

If you want custom value in "error" field then you can either specify the type to the one you're using or leave errorInfo type variable polymorphic. The later has the advantage that different types can be used for different REST API resources/endpoints:

type ErrorResponse errorInfo = Rfc7807Error ErrorType errorInfo ()

data ErrorType
    = DocumentNotFound
    {- ... -}

instance ToJSON ErrorType where
    toJSON = \case
        DocumentNotFound ->
            -- The URL doesn't have to be absolute. See description of
            -- $sel:type_:Rfc7807Error field of Rfc7807Error for more information.
            String "https://example.com/docs/error#document-not-found"
        {- ... -}

While it is possible to use Rfc7807Error directly, using newtype allows to be more flexible with how things are encoded. If you're expecting your use cases to evolve over time it is good to start with something like this:

-- | See "Type Alias" section for @ErrorType@ example.
data ErrorType
  = {- ... -}

newtype ErrorResponse = ErrorResponse
    { errorResponse :: Rfc7807Error ErrorType () ()
    }

-- Following encoding example is very simple, basicaly the same thing as the
-- default Rfc7807Error encoding. However, it's a template that when
-- copied allows us to adjust bits that we want different.

errorResponseEncodingOptions :: EncodingOptions
errorResponseEncodingOptions = defaultEncodingOptions
    { $sel:omitExtensionField:EncodingOptions = const True
    }

instance ToJSON ErrorResponse where
    toJSON :: ErrorResponse -> Value
    toJSON ErrorResponse{..} =
         object . toKeyValue errorResponseEncodingOptions
    {- ... -}

instance FromJSON ErrorResponse where
    parseJSON :: ErrorResponse -> Value
    parseJSON = withObject "ErrorResponse" \o ->
         ErrorResponse $ parseObject errorResponseEncodingOptions o

This is an elaboration of the previous "Newtype" example. We will use errorInfo and context type arguments of Rfc7807Error to include more information. The errorInfo will be kept polymorphic so that each HTTP response can use a different one, depending on its needs.

-- | See "Type Alias" section for @ErrorType@ example.
data ErrorType
  = {- ... -}

-- | We can use a concrete data type or we can use something flexible like
-- Object (actually a @HashMap Text Value@) allowing us to
-- include any kind of metadata.
--
-- This approach intentionally resembles structured logging approach like
-- the one used by katip library.
type ErrorContext = Object

newtype ErrorResponse e = ErrorResponse
    { errorResponse :: Rfc7807Error ErrorType e ErrorContext
    }

-- Following serialisation example is just one of many possibilities. What
-- it illustrates is how much flexibility we have. Not only we can rename
-- fields through $sel:extensionFieldName:EncodingOptions, we can also play with the encoding
-- to get something that is more suitable for our system.

-- | What we'll do is serialise the @ErrorContext@ manually. To be able to
-- do that we need to tell toKeyValue and parseObject to ignore the
-- extension field.
--
-- Another thing that we'll do is that we'll rename the "error" field to
-- "error_message". This is one of those things that are useful when
-- we are changing existing error responses.
errorResponseEncodingOptions :: EncodingOptions
errorResponseEncodingOptions = defaultEncodingOptions
    { $sel:omitExtensionField:EncodingOptions = \case
        ErrorField -> False
        ContextField -> True

    , $sel:extensionFieldName:EncodingOptions = \case
        ErrorField -> "error_message"
        name -> $sel:extensionFieldName:EncodingOptions defaultEncodingOptions name
    }

instance ToJSON => ToJSON (ErrorResponse e) where
    toJSON :: ErrorResponse -> Value
    toJSON ErrorResponse{errorResponse} = Object
        ( toKeyValue errorResponseEncodingOptions errorResponse
        -- We'll take everything that's in context and put it directly into
        -- the top-level JSON object.
        --
        -- The downside of this approach is that we need to be careful not
        -- to redefine already existing fields. What we could do is change
        -- the field names. It is quite common to use "@fieldName" or
        -- similar convention for metadata.
        --
        -- If we go with custom data type we can then examine if it's JSON
        -- object or not. If not we can instead put it into the "context"
        -- field as a kind of a default.
        <> context errorResponse
        )
    {- ... -}

instance FromJSON e => FromJSON (ErrorResponse e) where
    parseJSON :: ErrorResponse -> Value
    parseJSON = withObject "ErrorResponse" \o ->
         errorResponse <- parseObject errorResponseEncodingOptions o

         -- Now we'll take all the fields that are not part of RFC7807 or
         -- "error" and put them into context.
         let context = flip filterWithKey o \k _v ->
                 k notElem parsedFields

         pure ErrorResponse
             { errorResponse = errorResponse{context}
             }
       where
         parsedFields =
             -- These hardcoded values are okay since RFC7807 defines the
             -- names and we cannot change them.
             [ "type", "title", "status", "detail", "instance"
             , $sel:extensionFieldName:EncodingOptions ErrorField
             ]

At this point we may want to provide few helper functions for constructing ErrorResponse (also known as smart constructors) to fit in nicely with the rest of our code base and HTTP framework we are using. You may want to look at Servant.Server.RFC7807 module, even if you're using a different framework. It should give you few ideas on how to proceed.