In Part 1, we discussed what made us choose GraphQL for a client project. Part 2 recapped everything we learned working with GraphQL.

After all that, how would we recommend those less familiar with GraphQL use the technology?

Takeaways

So, is GraphQL the right technology for your project? Maybe! Like any technology, GraphQL has strengths and weaknesses that need to be weighed against the requirements of a project. As long as you’re aware of the constraints of this new technology, we have no doubt you’ll gain benefit from it. If you’re just starting a project with GraphQL, we’d make a few recommendations:

Be aware of the Apollo iOS SDK’s data & caching models

While the Apollo iOS SDK is absolutely the fastest way to start coding against a GraphQL API, it comes with a few quirks. Weighing the pros & cons of those quirks will help you decide if this is right for your project. If you decide it is, be aware that these constraints on the query models & caching are ones you’ll have to work around.

Hash out the schema early

The GraphQL schema is a unique concept that powers a lot of the GraphQL perks. The sooner it’s built, the sooner the frontend and backend teams can start building. Theoretically, anyone who has access to the app designs should be able to design the schema. To avoid assumptions that might result in an untenable schema, the frontend and backend teams should design the schema together.

Err towards flexibility when designing the schema

It is important to note that the GraphQL schema is not the same as the type definitions of a strongly typed programming language, even though they look similar. GraphQL queries are often resolved from external data sources that might fail for reasons beyond our control. Because of this, it is a good rule of thumb to make queries and fields nullable as default. Even fields that seem guaranteed to exist, like a user’s first name on a user query, might need to be nullable at some point if you wanted to restrict certain fields on a query based on the requestor’s authorization level.

GraphQL and REST endpoints can coexist in the same server

We used REST endpoints for authentication. There were reasons it would have been better to handle authentication and authorization in GraphQL queries, but it’s not because they were RESTful.

Building a GraphQL API allowed us to partially decouple frontend and backend development. It also gave us access to powerful and convenient utilities. If you’re considering adopting GraphQL for a project, weigh the pros and cons as you would before buying into any other technology. If you decide it is a good fit for your use case, you’re likely to find a lot of value in GraphQL.

The post Using GraphQL in Production iOS Applications – Part 3 appeared first on Big Nerd Ranch.

In Part 1, we discussed what made GraphQL an attractive technology for one of our client projects. We ended up learning a good amount about the technology.

Here’s what was great, what was okay, and what was disappointing about the experience.

What worked

Schema as Contract

Initial, rapid prototyping of our backend data model was incredibly easy. All it took was an initial GraphQL schema as a contract for both teams to build against. Apollo Server can serve a simple mock server based on the schema with zero configuration, and it is straightforward to expand the mock server’s functionality.

Expanding the schema was also trivial. So long as the only changes were additive, the backend could quickly revise the API to support new properties or new objects. Existing clients could only ask for properties they already knew about, so all prior builds would just work without issue.

Efficient Queries

The frontend was able to get the data needed and nothing more with a minimum amount of requests.

What sorta worked

Authorization

There’s not a GraphQL standard for authorization. Because we were building a server that only had one level of authorization for users, we used standard REST endpoints for logging in, and then gave authenticated users unrestricted access to the GraphQL queries. This wouldn’t work with a more complex security model. The lack of standard here was uncomfortable, especially in an app that needed to be HIPAA compliant. Apollo Server does suggest a solution, though.

Automatically Generated Models

These worked great and saved us a lot of time early in development. However, two requests that ask for the exact same object with the exact same properties are, in fact, two different types. While this can be solved by GraphQL’s Fragments, they begin to etch away at what made these models so easy to use in the first place. We only just reached the point where the complexity of Fragments was needed before this project ended, so it’s unclear if it’d be best to keep going with Fragments or implement our own model layer.

Instead, we worked around that by making as few requests as possible so we could share types. The impact of that was…

Maximized Bandwidth

Unfortunately, “get all the data with minimal queries” is the antithesis of “only ask for the data you need, when you need it”. Most of our queries asked for a single model, and for all the properties on that model. That became the generated type for that model that we used throughout the app. We absolutely didn’t take advantage of batching queries together, or only asking for minimal data. Indeed, it would be exceedingly difficult to take advantage of that without a translation layer from the query-generated models into the app’s data model.

Decoupled Development

The schema is at the core of developing a GraphQL app, and it is a net gain to dev speed. However, because of its central role, non-additive modifications do require coordination between frontend and backend teams. This means that development is not entirely decoupled.

For example, changing existing types and fields broke existing clients that were built with an older schema. This isn’t surprising and on-par with the effects of making a breaking change to a REST implementation. Still, those breaking changes snuck up on us more than they should have. Additionally, every breaking schema change required a code change on the client. This was not only to rebuild the query models, but also to propagate the property names and type changes throughout the codebase.

All this highlights a gap between the promise & execution of GraphQL. While the schema is a wonderful source of truth, without perfect foreknowledge it’s actually a very sensitive dependency.

What did not work

Batching? We don’t need no stinking batching.

Despite the fact that we weren’t making any batch requests, the Apollo response could still contain both data and errors, as if we had made a batch request. This meant every request had 3 results (success, partial success, and error) rather than simply “success” & “error”. This complexity was a pain, and was unavoidable.

Caching in the Apollo iOS SDK

A sane person wouldn’t cache a response with an error. Unfortunately, that’s exactly the default configuration for caching in the Apollo iOS SDK. While that’s been reported as a bug, the lack of support forced us to choose between functional caching or a schema that allowed nullable queries, a central concept of GraphQL. Both options are likely to become unacceptable at a certain point.

Not only does the JavaScript SDK have a more sane default, it also has configuration options that are completely inaccessible in the iOS SDK. This reinforces the notion that the iOS SDK is a second-class citizen, and that they’re not really looking to actively fix bugs found in it.

Is it right for you?

In Part 3, we reflect on all we’ve learned and let you know what you should consider when using GraphQL in your project to maximize the benefit while minimizing the costs.

The post Using GraphQL in Production iOS Applications – Part 2 appeared first on Big Nerd Ranch.

GraphQL is a technology that’s rapidly rising in popularity. Here at Big Nerd Ranch, we always like to use the best available tool to solve our customer’s problems. We recently had a client project which looked like a great fit for this new technology. We spent three months working with GraphQL as our main API design for an iOS app.

In this series of blog posts, we’ll look at what made GraphQL an appealing technology, the benefits and shortfalls we discovered while using it, and what we recommend others do when considering using this technology in their own projects. Let’s get started!

Why GraphQL

There are a handful of useful features that GraphQL promises. They are:

Decoupled frontend and backend development

Once the GraphQL schema is defined, it is trivial to deploy a mock server that the frontend devs can build against while the real backend is implemented.

Data fetching optimized for mobile

The get-what-you-ask-for approach of GraphQL saves bandwidth. The client can ask for multiple screens worth of data in one request, which would be multiple requests in a traditional REST API.

Client controls the network cost

GraphQL is designed to minimize the cost of fetching data from an app. You can batch multiple requests for independent objects together to minimize the number of network connections. You can specify exactly which properties you need from those models to minimize the payload. And this can all be done dynamically on the client side, without a deployed change to the API.

Robust tooling

Apollo has a large suite of libraries that seem to meet all GraphQL needs. Apollo Server claims it is, “The best way to quickly build a production-ready, self-documenting API for GraphQL clients, using data from any source.”

Type-safe models for free

One of the promises of the Apollo GraphQL iOS SDK is that it automatically builds type-safe models that match your GraphQL queries. We don’t need to build codable models separate from our queries – if we want a new model or a new property we just need to ask for it. The build system handles the rest.

Why not GraphQL

Let’s play devil’s advocate for a minute. What are some good reasons to not use GraphQL on a project?

REST is well established

REST has been the standard means of building APIs for years now. It’s well understood by both our backend team and our mobile team. If you have a solid understanding of what the primary objects were in your data model, a REST service is relatively easy to create.

Unknown unknowns

The biggest risk anytime you adopt a new technology is that you have gaps in your understanding that don’t surface until something fails. Documentation isn’t a perfect substitute for experience.

Decision time

On this particular client project, a few key points tipped us towards using GraphQL:

• The API’s clients will only be mobile apps. Since GraphQL is designed to be consumed by mobile clients, that’s a clear point in its favor.
• The data model is subject to change. While this can be done with REST, the schema-based approach of GraphQL can make changes to the data model easier to implement and mock.
• We had read plenty on the draw of GraphQL and were comfortable with its tradeoffs.

How did it go? Check out Part 2 to see.

The post Using GraphQL in Production iOS Applications – Part 1 appeared first on Big Nerd Ranch.