dataservice.http
Module dataservice.http
API
ballerina/dataservice.http Ballerina library
Overview
The ballerina/dataservice.http package is the HTTP runtime of the data services that bal persist generates from a persist model. Generated HTTP services call it to build error responses and Location headers, so fixes reach them without regeneration.
Key Features
- Status code records for each response of a data service, with the
DataserviceErrorbody - Mapping of persist and query errors to
400,404,409and500responses - An authenticator that checks Basic, JWT and OAuth2 credentials and each operation's scopes before dispatch
Locationheaders for created records, and the runtime settings: port, listener, CORS, auth and page sizes
Quick start
The package is used by generated code, not imported by hand. To generate an HTTP data service:
-
Add the persist entry with an HTTP data service to the package:
bal persist add --datastore h2 --dataservice http -
Annotate each entity to expose in
persist/model.balwith@dataservice:Expose. -
Build and run the package. The service is served on port
9090under/api:bal run curl localhost:9090/api/employees
A failed request is answered with a status code and a JSON body that names the error category:
GET /api/employees/99 → 404 {"code": "NOT_FOUND", "message": "A record with the key '99' does not exist for the entity 'Employee'."}
For the details, see the specification.
Functions
checkRelationScopes
function checkRelationScopes(RequestContext ctx, string entity, string relation, string target, string[] scopes) returns Forbidden?Checks that the caller may read a related entity.
Parameters
- ctx RequestContext - The request context, in which
Authenticatorkeeps the caller
- entity string - The name of the entity
- relation string - The relation field
- target string - The name of the related entity
- scopes string[] - The
readscopes of the related entity
Return Type
- Forbidden? -
Forbiddenwhen the caller holds none of the scopes, or()
hasScope
function hasScope(RequestContext ctx, string[] scopes) returns booleanTells whether the caller of the request holds one of the scopes. An empty list takes the scopes of the provider that authenticated the caller, and holds when the provider sets none.
Parameters
- ctx RequestContext - The request context, in which
Authenticatorkeeps the caller
- scopes string[] - The scopes
Return Type
- boolean - Whether the caller holds one of them;
falsewhen the request was not authenticated
setErrorBody
Sets the data service error body on a response that ballerina/http built for an error raised before a resource
runs, such as a binding or dispatching error, keeping its status code.
toCreateError
function toCreateError(error err, string entity) returns Conflict|ConstraintViolation|InternalErrorMaps an error from creating records, or from reading a created record back, to its response.
Return Type
- Conflict|ConstraintViolation|InternalError - The
409or500response
toDeleteError
function toDeleteError(error err, string entity, KeyValue[] key) returns NotFound|ConstraintViolation|InternalErrorMaps an error from deleting a record to its response.
Parameters
- err error - The error the persist client returned
- entity string - The name of the entity
- key KeyValue[] - The values of the record's key fields, in key order
Return Type
- NotFound|ConstraintViolation|InternalError - The
404,409or500response
toGetError
function toGetError(error err, string entity, KeyValue[] key, string operation) returns NotFound|InternalErrorMaps an error from reading one record to its response.
Parameters
- err error - The error the persist client returned
- entity string - The name of the entity
- key KeyValue[] - The values of the record's key fields, in key order
- operation string (default "get one") - The name of the operation, which is logged with the error
Return Type
- NotFound|InternalError - The
404or500response
toInvalidInput
function toInvalidInput(ConversionError err, string entity, string 'field) returns InvalidInputMaps a field value that is not in its JSON format to the 400 response.
Parameters
- err ConversionError - The error from the
ballerina/dataserviceconversion
- entity string - The name of the entity
- 'field string - The name of the field
Return Type
- InvalidInput - The
400response
toListError
function toListError(error err, string entity, string operation) returns InternalErrorMaps an error from reading many records to the 500 response.
Parameters
- err error - The error the persist client returned
- entity string - The name of the entity
- operation string (default "get many") - The name of the operation, which is logged with the error
Return Type
- InternalError - The
500response
toLocation
Builds the Location of a created record.
Parameters
- path string - The path of the entity's collection, such as
/api/employees
- key KeyValue[] - The values of the record's key fields, in key order
Return Type
- string - The path of the record, such as
/api/employees/1
toQueryError
function toQueryError(DataserviceError|ConversionError err, string entity) returns InvalidInputMaps an invalid query option to the 400 response.
Parameters
- err DataserviceError|ConversionError - The error body, or the conversion error of a filter value, from
dataservice:toQueryordataservice:checkFields
- entity string - The name of the entity
Return Type
- InvalidInput - The
400response
toUpdateError
function toUpdateError(error err, string entity, KeyValue[] key) returns NoContent|NotFound|Conflict|ConstraintViolation|InternalErrorMaps an error from updating a record to its response. An update that is saved but cannot be read back has no record.
Parameters
- err error - The error the persist client returned
- entity string - The name of the entity
- key KeyValue[] - The values of the record's key fields, in key order
Return Type
- NoContent|NotFound|Conflict|ConstraintViolation|InternalError - The
204,404,409or500response
Classes
dataservice.http: Authenticator
Authenticates each request of a data service with auth and checks the scopes of its operation, before
ballerina/http dispatches the request and binds its parameters.
Constructor
Checks the authentication providers and creates their handlers.
init (ListenerAuthConfig[] providers, map<map<string[]>> scopes, CorsConfig cors)- providers ListenerAuthConfig[] - The value of
dataserviceConfig.serviceConfig.auth
- cors CorsConfig {} - The service's CORS settings, applied to the
401and403responses
authorize
function authorize(RequestContext ctx, Request request, string[] path) returns NextService|Unauthorized|Forbidden|error?Authenticates the request, keeps the caller in the request context, and checks that the caller holds a scope
of the operation, or, for an operation without scopes, a scope of the provider that authenticated it. An
OPTIONS request, such as a CORS preflight, is passed on without a credential.
Parameters
- ctx RequestContext - The request context
- request Request - The request
- path string[] - The request's path, relative to the service
Return Type
- NextService|Unauthorized|Forbidden|error? - The next service,
Unauthorizedwithout a valid credential, orForbiddenwithout a scope
Records
dataservice.http: AuthConfig
The runtime settings of a generated HTTP data service with auth.
Fields
- Fields Included from *Config
- listenerConfig ListenerConfiguration(default {}) - The other settings of the listener, such as TLS
- serviceConfig AuthServiceConfig - The settings of the service, with the authentication providers
dataservice.http: AuthServiceConfig
The settings of a generated service with auth.
Fields
- Fields Included from *ServiceConfig
- cors CorsConfig
- auth ListenerAuthConfig[] - The authentication providers, such as a JWT validator
dataservice.http: Config
The runtime settings of a generated HTTP data service, the type of its configurable dataserviceConfig.
Fields
- Fields Included from *Config
- listenerConfig ListenerConfiguration(default {}) - The other settings of the listener, such as TLS
- serviceConfig ServiceConfig(default {}) - The settings of the service
dataservice.http: Conflict
The response to a write that conflicts with an existing record.
Fields
- Fields Included from *Conflict
- body DataserviceError - The error body, with the code
CONFLICT
dataservice.http: ConstraintViolation
The response to a write that violates a constraint of the entity.
Fields
- Fields Included from *Conflict
- body DataserviceError - The error body, with the code
CONSTRAINT_VIOLATION
dataservice.http: Forbidden
The response to a caller without a scope of the action, or, for get related or a relation in fields, without a
read scope of the related entity.
Fields
- Fields Included from *Forbidden
- body DataserviceError - The error body, with the code
FORBIDDEN
dataservice.http: InternalError
The response to a request that failed for any other reason.
Fields
- Fields Included from *InternalServerError
- body DataserviceError - The error body, with the code
INTERNAL
dataservice.http: InvalidInput
The response to a request with a value that is not in its format.
Fields
- Fields Included from *BadRequest
- body DataserviceError - The error body, with the code
INVALID_INPUT
dataservice.http: NotFound
The response to a request for a record that does not exist.
Fields
- Fields Included from *NotFound
- body DataserviceError - The error body, with the code
NOT_FOUND
dataservice.http: ServiceConfig
The settings of the generated service that vary by environment.
Fields
- cors CorsConfig(default {}) - The CORS settings; no cross-origin request is allowed by default
dataservice.http: Unauthorized
The response to a request without a valid credential, returned by Authenticator.
Fields
- Fields Included from *Unauthorized
- body DataserviceError - The error body, with the code
UNAUTHENTICATED
Import
import ballerina/dataservice.http;Other versions
0.1.0
Metadata
Released date: 1 day ago
Version: 0.1.0
License: Apache-2.0
Security
No known vulnerabilities in libraries
Checked on 2026-11-21 via OSV.dev
Compatibility
Platform: any
Ballerina version: 2201.14.0
GraalVM compatible: Yes
Pull count
Total: 4
Current verison: 4
Weekly downloads
Keywords
dataservice
persist
http
Type/Library
Area/Database
Name/Data Service HTTP
Contributors