@cap-js/graphql

CDS protocol adapter for GraphQL

About this project

A GraphQL protocol adapter for SAP Cloud Application Programming Model Node.js. This adapter generically generates a GraphQL schema for the models of an application and serves an endpoint that allows you to query your services using the GraphQL query language.

WARNING: This package is in an early general availability state. This means that it is generally available, with stable APIs unless otherwise indicated, and you can use it for production. However, please note the current limitations listed below.

Requirements and Setup

• Simply add the GraphQL adapter to your project using npm:

  npm add @cap-js/graphql
  

This command will set up the GraphQL plug-in with the @sap/cds runtime. It enables the new middlewares architecture in Node.js and registers a GraphQL endpoint at /graphql serving all CRUD requests for the application services found in your model.

• Annotate the services you want to serve, e.g. using @graphql or @protocol: 'graphql'.

• Run your server as usual, e.g. using cds watch.

The runtime will serve all annotated services via GraphQL at the default configured endpoint.

Limitations

• Actions and functions are not yet supported.
• CDS annotations like @readonly aren’t considered during schema generation.
• Cursor-based Pagination – we currently support offset-based pagination, and will add cursor-based pagination going forward. While we intend to support both variants then, it is not guaranteed that we can do so without breaking changes to current behaviour.
• Extensions are not yet considered.

Support, Feedback, Contributing

This project is open to feature requests/suggestions, bug reports etc. via GitHub issues. Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our Contribution Guidelines.

Code of Conduct

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its Code of Conduct at all times.

Licensing

Copyright 2022 SAP SE or an SAP affiliate company and cap-js/graphql contributors. Please see our LICENSE for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available via the REUSE tool.

Changelog

Version 0.13.0 - 2025-07-11

Added

• Schema validation after schema generation (on server startup or manual compilation) to ensure that the generated schema is valid according to the GraphQL specification
• Scalar type Void that represents the absence of a return value and only allows value null

Fixed

• Improved schema generation robustness where specific CDS modelling could cause empty GraphQL types to be generated (which is not allowed) for entities, aspects and services. These types and any resulting empty parent types are omitted from the generated schema and a warning is logged for them. If schema generation would result in an empty query root type, a placeholder field _ of type Void is added to keep the schema valid.