We are happy to present our users the next generation Onedot API, a comprehensive set of operations to automate product data onboarding to the maximum, from transferring data files like product data catalogues to setting up and running onboarding jobs, assigning feedback tasks, retrieving performance statistics and key measurements to finally downloading onboarded product data in the right format and the right structure: consumable data!
For quite some time now, our customers have been using our first generation Onedot API which was based on the OpenAPI 2.0 standard, a widely used approach to open up REST (Representational State Transfer), RESTful or REST-like APIs to the world. A set of open-source tools built around the OpenAPI 2.0 and 3.0 specifications can help you design, build, document and consume REST APIs. Browser-based editors allow you writing the OpenAPI specs, other tools render OpenAPI specs as interactive API documentation or even generate client library code for your API in over 40 languages!
The OpenAPI 2.0 standard promotes a design-first approach: Use code generation to transform a valid API specification into server-side stubs and implement the server login with just a few lines of code. While this approach proves superior to alternative API designs in many cases, the somehow close relationship to the REST paradigm also implies some disadvantages:
Based on those observations, we evaluated GraphQL as a more modern and powerful alternative, embracing all advantages of the OpenAPI standard while getting the better of the two classic REST limitations which are data filters and data relationships. These flaws force REST clients to always receive a full payload in response and hit multiple data stores separately, taking up bandwidth and increasing response time of an application.
GraphQL in essence is not an API, but a data query and manipulation language for APIs. Originally created and open-sourced by Facebook, it solves the problem of unoptimised data flow between mobile apps or SPAs, and a backend, be it micro-services, server-less endpoints or a traditional monolith. GraphQL is a syntax describing the way or requesting data from the server. The main difference of GraphQL compared to traditional REST APIs is that the response format transmitted in the query itself and defined by the client rather than the server. GraphQL APIs are organised in terms of types and fields, not endpoints. Accessing the full capabilities of your data happens from a single endpoint, in a language-agnostic way.
Similar to OpenAPI, the core notion of using GraphQL is a schema specification which strictly defines data structure and regulates how data can be accessed. There are two basic types of GraphQL operations:
The strict separation into queries and mutations follows the CQS (Command-Query Separation principle), essentially enforcing operations either to be a command that performs an action, or a query that returns data to the caller, but not both. In other words, asking a question should not change the answer. Besides having a simplifying effect on API clients or applications in general, it makes states (via queries) and state changes (via commands) more comprehensible. For the sake of minimising server calls when interacting with a GraphQL endpoint, it is considered good practice to let mutations return the updated state (after the state change) to the API client, saving another service call to retrieve the latest state.
With those things in mind, we announce the immediate availability of the Onedot API 2.0, a GraphQL-based endpoint to automate all aspects of the Onedot Platform! Check out our comprehensive API reference documentation, take a test-drive in our API Playground, and use your favourite GraphQL client to seamlessly interact with Onedot. Most API queries and mutations need authentication, requiring an API Key to be passed using the HTTP X-API-Key header with every request.
To get started with your first queries, request an API Key by contacting us at support@onedot.com. We love to hear how you use the Onedot API, just write us and let us know your feedback.
