JSON

    So our next example shows how to fetch some JSON data, allowing us to press a button to show random cat GIFs. Click the blue “Edit” button and look through the program a bit. Try not to only look at the cats! Click the blue button now!

    Edit

    This example is pretty similar to the last one:

    • starts us off in the Loading state, with a command to get a random cat GIF.
    • update handles the GotGif message for whenever a new GIF is available. Whatever happens there, we do not have any additional commands. It also handles the MorePlease message when someone presses the button, issuing a command to get more random cats.
    • view shows you the cats!

    The main difference is in the getRandomCatGif definition. Instead of using Http.expectString, we have switched to Http.expectJson. What is the deal with that?

    When you ask for a random cat GIF, their server produces a big string of JSON like this:

    1. {
    2.   "data": {
    3.     "type": "gif",
    4.     "id": "l2JhxfHWMBWuDMIpi",
    5.     "title": "cat love GIF by The Secret Life Of Pets",
    6.     "image_url": "https://media1.giphy.com/media/l2JhxfHWMBWuDMIpi/giphy.gif",
    7.     "caption": "",
    8.     ...
    9.   },
    10.   "meta": {
    11.     "status": 200,
    12.     "msg": "OK",
    13.     "response_id": "5b105e44316d3571456c18b3"
    14. }

    We have no guarantees about any of the information here. The server can change the names of fields, and the fields may have different types in different situations. It is a wild world!

    In JavaScript, the approach is to just turn JSON into JavaScript objects and hope nothing goes wrong. But if there is some typo or unexpected data, you get a runtime exception somewhere in your code. Was the code wrong? Was the data wrong? It is time to start digging around to find out!

    In Elm, we validate the JSON before it comes into our program. So if the data has an unexpected structure, we learn about it immediately. There is no way for bad data to sneak through and cause a runtime exception three files over. This is accomplished with JSON decoders.

    JSON Decoders

    Say we have some JSON:

    1. {
    2.     "name": "Tom",
    3.     "age": 42
    4. }

    We need to run it through a Decoder to access specific information. So if we wanted to get the "age", we would run the JSON through a Decoder Int that describes exactly how to access that information:

    If all goes well, we get an Int on the other side! And if we wanted the "name" we would run the JSON through a Decoder String that describes exactly how to access it:

    If all goes well, we get a String on the other side!

    How do we create decoders like this though?

    The package gives us the module. It is filled with tiny decoders that we can snap together.

    So to get "age" from { "name": "Tom", "age": 42 } we would create a decoder like this:

    The function takes two arguments:

    1. String — a field name. So we are demanding an object with an "age" field.
    2. Decoder a — a decoder to try next. So if the "age" field exists, we will try this decoder on the value there.

    So putting it together, field "age" int is asking for an "age" field, and if it exists, it runs the Decoder Int to try to extract an integer.

    We do pretty much exactly the same thing to extract the "name" field:

    1. import Json.Decode exposing (Decoder, field, string)
    3. nameDecoder : Decoder String
    4. nameDecoder =
    5.   field "name" string
    7. -- string : Decoder String

    In this case we demand an object with a "name" field, and if it exists, we want the value there to be a String.

    Nesting Decoders

    1. {
    2.   "data": {
    3.     "type": "gif",
    4.     "id": "l2JhxfHWMBWuDMIpi",
    5.     "title": "cat love GIF by The Secret Life Of Pets",
    6.     "image_url": "https://media1.giphy.com/media/l2JhxfHWMBWuDMIpi/giphy.gif",
    7.     "caption": "",
    8.     ...
    9.   "meta": {
    10.     "status": 200,
    11.     "msg": "OK",
    12.     "response_id": "5b105e44316d3571456c18b3"
    13.   }
    14. }

    We wanted to access to show a random GIF. Well, we have the tools now!

    This is the exact gifDecoder definition we used in our example program above! Is there a "data" field? Does that value have an "image_url" field? Is the value there a string? All our expectations are written out explicitly, allowing us to safely extract Elm values from JSON.

    That is all we needed for our HTTP example, but decoders can do more! For example, what if we want two fields? We snap decoders together with :

    1. map2 : (a -> b -> value) -> Decoder a -> Decoder b -> Decoder value

    This function takes in two decoders. It tries them both and combines their results. So now we can put together two different decoders:

    1. import Json.Decode exposing (Decoder, map2, field, string, int)
    3. type alias Person =
    4.   { name : String
    5.   , age : Int
    6.   }
    8. personDecoder : Decoder Person
    9. personDecoder =
    10.   map2 Person
    11.       (field "name" string)
    12.       (field "age" int)

    So if we used personDecoder on { "name": "Tom", "age": 42 } we would get out an Elm value like Person "Tom" 42.

    If we really wanted to get into the spirit of decoders, we would define personDecoder as map2 Person nameDecoder ageDecoder using our previous definitions. You always want to be building your decoders up from smaller building blocks!

    Next Steps

    There are a bunch of important functions in Json.Decode that we did not cover here:

    • : Decoder Bool
    • list : Decoder a -> Decoder (List a)
    • : Decoder a -> Decoder (Dict String a)

    So there are ways to extract all sorts of data structures. The oneOf function is particularly helpful for messy JSON. (e.g. sometimes you get an Int and other times you get a String containing digits. So annoying!)

    There are also map3, , and others for handling objects with more than two fields. But as you start working with larger JSON objects, it is worth checking out . The types there are a bit fancier, but some folks find them much easier to read and work with.