# Harmonizing APIs OpenAPI vs GraphQL with Spotify > [! note]- > The content of this page is generated by audio/video transcription and text transformation from the content and links of this source. Source: [https://fosdem.org/2025/schedule/event/fosdem-2025-6001-harmonizing-apis-a-comparison-of-openapi-and-graphql-using-the-spotify-schema/](https://fosdem.org/2025/schedule/event/fosdem-2025-6001-harmonizing-apis-a-comparison-of-openapi-and-graphql-using-the-spotify-schema/) <video src="https://video.fosdem.org/2025/k4201/fosdem-2025-6001-harmonizing-apis-a-comparison-of-openapi-and-graphql-using-the-spotify-schema.av1.webm" controls></video> ## Summary & Highlights: This session at FOSDEM 2025, titled 'Harmonizing APIs: a comparison of OpenAPI and GraphQL using the Spotify schema', explores the challenges and solutions in integrating OpenAPI with GraphQL. Martin Bonnin, the speaker, shares insights from his experience in converting Spotify's REST API to GraphQL, highlighting the similarities and differences between OpenAPI and GraphQL. The talk discusses the importance of shared language in building safe and interoperable APIs, and suggests methods to ease the conversion process. **Introduction to API Harmonization** The session begins by introducing the concept of API harmonization, focusing on the integration of OpenAPI and GraphQL. Using the Spotify API as a case study, the talk highlights the challenges faced by developers in converting REST APIs to GraphQL. This section sets the stage for a deeper dive into the technical aspects of API integration. **Technical Comparison of OpenAPI and GraphQL** This section delves into the technical comparison between OpenAPI and GraphQL. It outlines the shared characteristics and differences, such as their approaches to schema versioning and feature discovery. The speaker explains how OpenAPI's flexibility and GraphQL's conciseness can be leveraged to create robust APIs. Practical examples from the Spotify API are used to illustrate these points. **Challenges in API Conversion** Here, the focus shifts to the specific challenges encountered in converting OpenAPI schemas to GraphQL. The speaker discusses issues such as the lack of metadata in GraphQL and the complexities of mapping JSON Schema types to GraphQL types. The session provides solutions and best practices to overcome these hurdles, emphasizing the importance of operation IDs and component reuse. **Conclusion and Future Directions** The session concludes with a reflection on the learnings from the conversion process and the potential for future developments in API harmonization. The speaker encourages the audience to adopt best practices in API design to facilitate easier integration and code generation, highlighting the role of community collaboration in advancing the field. ## Importance for an eco-social transformation The session highlights the importance of creating interoperable APIs, which is crucial for an eco-social transformation. Interoperable APIs enable seamless data exchange and integration across platforms, fostering collaboration and innovation. For eco-social designers, tools like GraphQL and OpenAPI can be leveraged to build sustainable digital infrastructures that support community-oriented projects. Challenges include navigating the technical complexities of API conversion and ensuring broad adoption of best practices. Socially, the focus on shared language and interoperability aligns with ethical considerations of inclusivity and accessibility in technology development. ## Slides: | | | | --- | --- | | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_001.jpg\|300]] | The first slide introduces the session, 'Harmonizing APIs: A comparison of GraphQL and OpenAPI using the Spotify API', presented by Martin Bonnin at Fosdem 2025. It sets the stage for a discussion on the integration of these two API technologies, using Spotify's API as a real-world example. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_002.jpg\|300]] | This slide highlights the Apollo Kotlin project, a GraphQL client for Kotlin, which Martin Bonnin is involved with. It underscores the connection between GraphQL and Kotlin, and how Apollo Kotlin facilitates the integration of GraphQL schemas with Kotlin models. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_003.jpg\|300]] | The slide outlines the process of generating Kotlin models from a GraphQL schema and query using Apollo Kotlin. It emphasizes the type-safety and integration capabilities of Apollo Kotlin in building robust applications. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_004.jpg\|300]] | This slide presents a showcase of Spotify's API, demonstrating how Apollo's products and GraphQL are used in practice. It illustrates the application of GraphQL in accessing and interacting with Spotify's well-documented REST API. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_005.jpg\|300]] | The slide provides links to Spotify's REST API documentation and OpenAPI schema, serving as a resource for developers interested in exploring Spotify's API capabilities and structure. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_006.jpg\|300]] | This slide discusses the process of generating code from OpenAPI schemas and GraphQL schemas using Apollo Kotlin. It highlights the importance of code generation in streamlining API development and integration. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_007.jpg\|300]] | The slide marks the beginning of a deeper exploration into the technical aspects of API harmonization, signaling a transition from introductory concepts to detailed analysis. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_008.jpg\|300]] | This slide presents an example of an OpenAPI schema for Spotify's Web API, detailing the structure and metadata involved in defining API paths and responses. It serves as a foundation for understanding the conversion process to GraphQL. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_009.jpg\|300]] | The slide continues the discussion on OpenAPI schemas, focusing on the goal of converting these schemas into GraphQL APIs. It underscores the importance of operation IDs and schema metadata in facilitating this conversion. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_010.jpg\|300]] | This slide highlights the metadata components of an OpenAPI schema, including versioning and server information, which are crucial for defining API endpoints and interactions. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_011.jpg\|300]] | The slide contrasts the metadata approach in OpenAPI with GraphQL, noting the absence of metadata in GraphQL schemas and the reliance on introspection for feature discovery. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_012.jpg\|300]] | This slide details the paths and operations defined in an OpenAPI schema, using Spotify's API as an example. It illustrates how paths are mapped to operations and responses within the schema. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_013.jpg\|300]] | The slide introduces the concept of root fields in GraphQL, showing how OpenAPI paths are translated into GraphQL queries. It highlights the role of operation IDs in naming and organizing GraphQL fields. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_014.jpg\|300]] | This slide discusses the properties of an OpenAPI schema, focusing on the fields and data types used to describe API responses. It emphasizes the mapping of these properties to GraphQL fields. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_015.jpg\|300]] | The slide continues the discussion on schema properties, showing how OpenAPI descriptions and data types are translated into GraphQL fields and documentation. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_016.jpg\|300]] | This slide introduces arrays in OpenAPI schemas, detailing how they are represented and described. It sets the stage for discussing their translation into GraphQL lists. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_017.jpg\|300]] | The slide elaborates on the representation of arrays in GraphQL, explaining how OpenAPI arrays are mapped to GraphQL lists and the importance of type definitions in this process. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_018.jpg\|300]] | This slide provides a comprehensive view of an OpenAPI schema, illustrating the structure and components involved in defining API paths, operations, and responses. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_019.jpg\|300]] | The slide highlights the concept of nullability in OpenAPI schemas, discussing how nullable fields are represented and the implications for GraphQL conversion. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_020.jpg\|300]] | This slide continues the exploration of nullability, emphasizing the importance of defining nullable fields in OpenAPI schemas and their impact on GraphQL schema generation. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_021.jpg\|300]] | The slide raises a question about the creation of new objects for each path in an API schema, prompting a discussion on the organization and reuse of schema components. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_022.jpg\|300]] | This slide introduces OpenAPI components, illustrating how they facilitate the reuse and organization of schema elements across different API paths and operations. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_023.jpg\|300]] | The slide provides an example of an OpenAPI path and response, showing how components are used to structure and reference schema elements for efficient API design. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_024.jpg\|300]] | This slide continues the discussion on OpenAPI components, highlighting their role in defining reusable schema elements and simplifying the API design process. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_025.jpg\|300]] | The slide further explores the use of components in OpenAPI schemas, demonstrating how they enable the organization and reuse of schema elements for consistent API development. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_026.jpg\|300]] | This slide discusses the integration of OpenAPI components into GraphQL schemas, illustrating the mapping of OpenAPI paths and components to GraphQL queries and types. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_027.jpg\|300]] | The slide introduces the use of 'allOf' for defining interfaces in OpenAPI schemas, showing how this concept is translated into GraphQL interfaces and type inheritance. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_028.jpg\|300]] | This slide discusses the use of 'oneOf' for defining unions in OpenAPI schemas, illustrating how this concept is mapped to GraphQL unions and the implications for schema design. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_029.jpg\|300]] | The slide revisits the structure of an OpenAPI schema, emphasizing the role of components and paths in defining API operations and responses. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_030.jpg\|300]] | This slide provides a comprehensive overview of an OpenAPI schema, illustrating the integration of components and paths in defining API operations and responses. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_031.jpg\|300]] | The slide poses a rhetorical question about the success of the conversion process, prompting a reflection on the challenges and achievements in API harmonization. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_032.jpg\|300]] | This slide revisits the structure of an OpenAPI schema, highlighting the integration of components and paths in defining API operations and responses. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_033.jpg\|300]] | The slide introduces GraphQL as a query language, illustrating how GraphQL queries are structured and executed to retrieve data from APIs. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_034.jpg\|300]] | This slide discusses the concept of cycles in API schemas, highlighting the potential for recursive data structures and the challenges they pose for API design. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_035.jpg\|300]] | The slide continues the discussion on cycles, illustrating how recursive data structures are represented in API schemas and the implications for API design. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_036.jpg\|300]] | This slide contrasts REST and GraphQL approaches, emphasizing REST's focus on resources and GraphQL's emphasis on queries and data retrieval. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_037.jpg\|300]] | The slide introduces the concept of variant types in OpenAPI schemas, illustrating how different representations of the same entity are defined and used. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_038.jpg\|300]] | This slide continues the discussion on variant types, highlighting the challenges of mapping these variants to a single GraphQL entity. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_039.jpg\|300]] | The slide features a quote from Martin Bonnin, emphasizing the challenges of automatically converting OpenAPI schemas to idiomatic GraphQL. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_040.jpg\|300]] | This slide provides guidelines for better code generation, highlighting best practices for defining OpenAPI schemas to facilitate seamless conversion to GraphQL. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_041.jpg\|300]] | The slide wraps up the session, summarizing the key differences and similarities between GraphQL and OpenAPI, and their respective strengths and weaknesses. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_042.jpg\|300]] | This slide thanks the audience and promotes the upcoming GraphQL Conf 2025, providing details on the event and encouraging participation. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_043.jpg\|300]] | The slide expresses gratitude to the audience and provides links to additional resources on GraphQL, OpenAPI, and related projects for further exploration. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_044.jpg\|300]] | This slide revisits the structure of an OpenAPI schema, illustrating the integration of components and paths in defining API operations and responses. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_045.jpg\|300]] | The slide provides an overview of an OpenAPI schema, highlighting the integration of components and paths in defining API operations and responses. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_046.jpg\|300]] | This slide revisits the structure of an OpenAPI schema, illustrating the integration of components and paths in defining API operations and responses. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_047.jpg\|300]] | The slide provides an overview of an OpenAPI schema, highlighting the integration of components and paths in defining API operations and responses. | ![[FOSDEM 2025/assets/Harmonizing-APIs-a-comparison-of-OpenAPI-and-Graph/preview_048.jpg\|300]] | This slide summarizes the structure of an OpenAPI schema, illustrating the integration of components and paths in defining API operations and responses. ## Links [Slides](https://fosdem.org/2025/events/attachments/fosdem-2025-6001-harmonizing-apis-a-comparison-of-openapi-and-graphql-using-the-spotify-schema/slides/238446/Harmonizi_0134AhJ.pdf) [Video recording (AV1/WebM)](https://video.fosdem.org/2025/k4201/fosdem-2025-6001-harmonizing-apis-a-comparison-of-openapi-and-graphql-using-the-spotify-schema.av1.webm) [Video recording (MP4)](https://video.fosdem.org/2025/k4201/fosdem-2025-6001-harmonizing-apis-a-comparison-of-openapi-and-graphql-using-the-spotify-schema.av1.mp4)