It’s time to integrate another API into your app.
That statement alone brings all these feelings to mind:
- Poring over the API documentation, teasing out the JSON requests and responses for each call you need to use
- Extracting a schema out of those requests and responses, being mindful of the structures, types, and required/optional state of each field
- Writing the Swift or Objective-C code to translate those JSON schema into an object model
Hours gone in an instant. Isn’t parsing and translation something a computer should be taking care of? It can, using a tool called Quicktype.
Quicktype is a tool available in several forms (web app, command line app, and Xcode extension) that autogenerates an object model using JSON examples you paste directly into the app. It supports either Swift or Objective-C output for Apple platforms, plus many other languages in the web and command line apps if you need broader language support.
The Multiple JSON mode is the one most useful for the API integration use case. In this mode, you add a Type in the left sidebar for each type of request/response, then paste example JSON objects under each type. Quicktype will parse those JSON objects, combine the information it finds from each of the given examples, and produce code for the object model on the right.
Quicktype uses the multiple examples given to figure out the best object model for the given JSON. It is smarter than just the basic JSON types: boolean, number, string, array, and object. For example:
- If all of the values for a property are an integer, it will produce an Int in the model, not a Double
- If a property is present in some examples and absent in others, it will make the Swift field optional
- If a property can take on values of different types, Quicktype will construct an enum type with pre-built methods to handle all of the variations
- If a property contains values such as ISO8601 dates or UUIDs, which are normally JSON strings, it will detect that and produce the proper type field in the output
The model generation has a number of switches that allow you to produce anything from a very basic struct model without any additional boilerplate code, to a full class model with initializer and mutators, convenience methods to parse from JSON, and integration with either the built-in URLSession or third-party Alamofire network frameworks.
Quicktype gets you 95% of the way there, maybe more if the schema you are targeting is simple. With schemaless data formats like JSON, the variety of structures and formats data can take on is very broad. More esoteric ones trip up Quicktype: I personally noticed problems where UUID fields weren’t automatically detected, and ISO8601 date fields in arrays were not handled properly by the method generated to do the array conversion. You may also need to play with the naming of your JSON examples a little bit to get good class/struct names in the final output.
A quick review of Quicktype’s output is highly recommended, but a short review and possible minor code cleanup beats an hours-long, manual documentation to code translation hands down.