APIful Blog We're obsessed with Web APIs


Try out GraphQL APIs - Powered by API Harmony

Aug 2, 2017 •

GraphQL is a quickly spreading style of building web APIs. GraphQL APIs allow clients to query for and receive exactly the data they need for their application. At IBM Research, we are looking into ways to easily expose existing, REST-like APIs via GraphQL. To get a glimpse of our work, in API Harmony, you can now interact with 3 selected APIs via GraphQL.



Image 1: Selected GraphQL APIs powered by API Harmony

Why GraphQL?

GraphQL was created by Facebook to mitigate a number of problems, including overfetching, API maintenance, and backwards compatibility. To fetch complex data, clients had to perform multiple requests, which is time-consuming in itself and typically involves transmitting superfluous data, which is not needed or used by the client. The large number of Facebook clients also had ever-changing, diverse data requirements, so that new API endpoints constantly needed to be added, and existing ones had to be evolved. Doing so was complicated by having to keep API implementations and their documentation in sync, which is especially important with weakly-typed APIs.

To mitigate these problems, Facebook created GraphQL in 2012. By resolving user-defined data queries, GraphQL interfaces can flexibly serve a variety of client requirements, producing exactly the data clients desire, and potentially bundling multiple request. GraphQL interfaces are typed, so that clients can more easily reason about possible errors at compile time and developers profit from build-in documentation that is tied to the API implementation. Extending the data exposed by GraphQL APIs does not affect client code, as existing queries still result in the exact same data. Integrated support for declaring data fields to be deprecated helps GraphQL APIs further to roll out breaking changes.

After using GraphQL internally for a few years, Facebook open-sourced the technology in 2015. Since then, various companies like GitHub, The New York Times, or Yelp have exposed GraphQL APIs.

Support to create GraphQL APIs

At IBM Research, we are looking into ways to enable providers of REST-like APIs to more easily assess and eventually adopt GraphQL. We have build technology that, for a given OpenAPI specification, generates a GraphQL API, whose queries are resolved against the original API. This idea has received some attention recently. In contrast to existing approaches, our technology supports various authentication mechanisms, sanitizes and de-sanitizes data to fulfill GraphQL requirements, and can create deeply nested GraphQL interfaces by supporting links from the latest OpenAPI Specification 3.

Play with GraphQL APIs

Using our technology, we made available three GraphQL APIs, automatically created based on their OpenAPI specifications:

For authentication, GitHub and Lyft use OAuth 2, requiring the user to authorize the GraphQL interface with their existing credentials. IBM Watson Language Translation requires credentials that can be obtained by provisioning an instance of the Language Translation service in Bluemix. Visit API Harmony to see example queries you can perform, and let us know what you think about the experience - either in the comments below or by contacting us via Twitter.

Share via a Tweet or follow us for everything APIs!