Beginning in v24.3, developers can create custom API endpoints using the WebApi entry point. A web API is a Java class that implements the WebApi interface and uses the @ExecuteAsUser and @WebApiInfo annotations.

Execute As

By default, Web API requests execute as the Request Owner, who is the authenticated user. You can change the default user by using ExecuteAsService within a block of code.

Web API Info

You must specify the following in the WebApiInfo annotation:

endpointName: A String containing the endpoint name, which is used in the URI. Must be snake case, for example, my_endpoint_name.
minimumVersion: A String containing the minimum Vault API version required to use the Web API. For example, v24.3. Calling a custom API with a version lower than the minimum results in a failure.
apiGroup: The Webapigroup the API belongs to. This determines the permission set required to use the API.

Web API Groups

Each Web API must be assigned to a Web API Group. Admins can manage Web API Groups from Admin > Configuration > Web API Groups.

You can create Web API Groups using the MDL Webapigroup component.

RECREATE Webapigroup my_apis__c ( 
label('My APIs'), 
description('A group for my custom Web Apis');

Each Vault can have up to 100 Webapigroups.

Permission Sets

Web API Groups must be assigned to Permission Sets. Admins can manage user access to Web API Groups from Admin > Users & Groups > Permission Sets > {permission_set} > API.

URI

The URI is determined by the endpointName value set in the WebApiInfo annotation in the following format:

POSThttps://{vaultDNS}/api/{version}/custom/{endpointName}

For example, the following annotation sets an endpointName value of my_endpoint_name.

@WebApiInfo(endpointName = "my_endpoint_name", minimumVersion = "v24.3", apiGroup = "my_api_group__c")

In a Vault with the DNS myvault.veevavault.com, this creates a custom endpoint with the following URI:

POSThttps://myvault.veevavault.com/api/v24.3/custom/my_endpoint_name

Requests

Web APIs only allow POST requests and accept either valid application/json or multipart/form-data input. Requests can include one (1) binary content file, but binary content cannot be read or parsed using the Vault Java SDK.

Responses

Web APIs always return a status code of 200 and must return a response status of either SUCCESS, FAILURE, or WARNING. You can create JSON data as response binary content or return a FileReference.

The following example creates a response with a JSON payload.

JsonObject data = jsonObjectBuilder.build();

return webApiContext.newWebApiResponseBuilder()
    .withData(data)
    .withResponseStatus(WebApiResponseStatus.SUCCESS)
    .build();

Errors

You can use WebApiError.Builder to set custom error types and messages for your Web API to return when the response status is FAILURE. Add your custom errors to FAILURE responses using WebApiFailureResponse.Builder.

return webApiContext.newWebApiFailureBuilder()
    .withErrors(
        VaultCollections.asList(
            webApiContext.newWebApiErrorBuilder()
                .withType("MY_CUSTOM_ERROR_TYPE")
                .withMessage("A custom error occured")
                .build()
        )
    ).build();

The example above creates the following response:

{
    "responseStatus": "FAILURE",
    "errors":[
       {
        "type":"MY_CUSTOM_ERROR_TYPE",
        "message":"A custom error occured"
       }
    ]
}

Versioning

Developers are responsible for versioning their changes.

Limits & Restrictions

Web APIs are subject to all current Vault Java SDK and Vault API limits, including the Burst Limit and Auth API Burst Limit. Additionally, Vault processes only one (1) concurrent thread per user. Up to 20 additional requests per user will be added to a queue. After reaching the limit of 20 requests in the wait queue, subsequent requests from the same user return an error.

Developers can create a maximum of 100 Web APIs and 100 Web API Groups.

Input and output payloads are limited to 4 GB for binary content or 30 MB for JSON.

Custom Web APIs