Licensed to be used in conjunction with basebox, only.
Microservices in basebox
Not all business logic can be covered with basebox' schema directives. To provide total freedom and flexibility, basebox can be extended using Microservices that can do virtually anything with a GraphQL request. If a GraphQL operation is defined as a Microservice operation, basebox passes it on without taking a look or handling it in any other way.
Microservices can be written in any programming language as long as they are able to process GraphQL requests.
Security Warning
If you let a microservice handle a request, this microservice can do basically anything it wants. basebox only verifies that the request has a valid access token (i.e. access token has a valid signature and is not expired), but everything else is up to the microservice.
This means that the author of the microservice is responsible to verify that the request has sufficient access rights and does not do anything it is not allowed to do. We also strongly recommend that the microservice verifies the access token signature, although this has already been done by basebox. Following a Zero Trust approach, you should not trust that all other parts of the system have not been compromised.
Example code for verifying access token sigatures can be found in our Rust bbjwt library or in our example Python microservice, namely its auth module.
See also the compliance document User Needs, Software Requirements Specification and Architecture Description.
How does it work?
The microservice you want to plug into your basebox server needs to do the following:
- Provide an endpoint that basebox can POST GraphQL requests to. In other words, it must provide an http(s) server that handles POST requests.
- Verify that the access token passed in the authorization header is valid and the user has all required rights to perform the request
- Handle the request in any way it wants, e.g. hit a database or do some calculation, ...
- Return a proper JSON response as expected by GraphQL clients
basebox will return this response as-is to the client.
Example Microservice
We published an example microservice written in Python here. You are welcome to use it as a basis for your own microservice.
Configuration
You configure basebox to use a microservice by specifying that a specific GraphQL operation should be handled by your microservice, so you configure this in your GraphQL schema file.
Example
Let's assume you want your microservice to handle a rather complicated user-onboarding process. For this purpose, you define a mutation in your schema file like this:
mutation {
userOnboarding(name: String!, dateOfBirth: String!): User
@bb_resolver(
_type: HTTP_SERVICE,
_url: "https://microservice.yourcompany.io/gql"
)
}
That's all you have to do on basebox' side.
Note that in the example, the microservice must return a User object that must be defined both in basebox' GraphQL schema and in the schema the microservice is working with.
More information can be found in the reference of the @bb_resolver directive.