From REST to GraphQL
Switching from REST to GraphQL offers significant benefits, primarily through enhanced flexibility and efficiency in data retrieval. With GraphQL, clients can request exactly the data they need in a single query, eliminating issues of over-fetching or under-fetching data common with REST. The use of a single endpoint simplifies API management, and the strongly-typed schema ensures precise, self-documenting APIs that facilitate better validation and type checking. Additionally, GraphQL's ability to handle complex nested queries in one request and support for real-time updates via subscriptions greatly improves performance and responsiveness, making it an ideal choice for modern applications that demand efficient, dynamic data interactions.
Please use our GraphQL API technical documentation
https://docs.carerix.io/graphql/welcome
Access
To get access to your specific Carerix application's GraphQL API, you will need to setup a confidential client in the Carerix Identity Access menu. Access to the Carerix application hence is required. Carerix users with the specific permissions to access this menu can help here. Usually users with the administrator role will have this permission out of the box.
The following steps will quickly guide you through the process of setting up a Client that will provide you with a Client ID and Client Secret (also known as the API token) which you will need to authenticate the GraphQL API against your Carerix application.
Step 1: login as a Carerix user with permissions to access the Identity Acces Menu in Carerix (typically an administrator).
The Identity access menu is located in the maintenance section of your left menu. Go there and select the Clients tab.
Step 2: Start creating a new client
Click on the new button and select whether you want to use a public client or a confidential client. Usually, for a regular website integration posting jobs and processing applications, a confidential client is sufficient.
In the context of OAuth 2.0 "confidential clients" and "public clients" refer to different types of applications that interact with the OAuth 2.0 authorization server. The distinction between them primarily concerns their ability to securely handle credentials. For more information on confidential and public clients, please refer to the dedicated article.
Step 3: Configuring the confidential client
For a confidential client you need to setup the following fields:
Name: you need to provide a name for your client. You can typically choose the name of the service that is going to connect with the GraphQL through this client. It makes it transparent in the future to see to whom or what was given access with this client.
Code: Code is a user-defined unique identifier. It can be used to query the client via the API. It also acts as a prefix for client’s resources, permissions and scopes if such client is a resource server. Format:
urn:{vendor}/{unique name]Default Scopes: scopes define the rights for an application (e.g. website or middle ware) to call an endpoint. Scopes are included in the token and if the scope that is needed for a specific endpoint is not present in the token, your request will be rejected (403). any request done will take into account the default scopes.
To connect with the GraphQL API as a replacement for CX REST API - for now (July 2024) it is required to use the following scope:
urn:cx/cx5Wrapper:data:manage
Optional Scopes: optional scopes appear in a token only if expliticly requested from identity server during token obtaining.
Active YES/NO: indicates whether the client can be used (YES) or not (NO)
Permissions: With permissions you can grant granular access (none, owner, office, all) for operations (create, read, update, delete) on entities. Not applicable to CR-prefixed GraphQL queries and mutations.
Get the access token url by clicking on OpenID Configuration
And get the token endpoint
Step 4: Use the client credentials
In Postman select Auth type OAuth2.0 and fill in the given credentials and Access Token url in the red fields shown below.
Please use our GraphQL API technical documentation
https://docs.carerix.io/graphql/welcome
And here are some examples: