Accelerator Global Resources
home
This library defines a set of resources that are commonly used in API specifications. This helps to standardize API definitions as well as to avoid writing a lot of boilerplate definitions.
Security Schemes
This library defines a single Basic Authentication scheme called BasicAuth, which uses standard headers.
Traits
| Trait Name | Description | Typical Usage |
|---|---|---|
| ErrorResponses | Defines a comprehensive set of error response codes | Add to any endpoint definition |
| PingResponse | Defines a standard structure for health reports | Add to the /ping endpoint |
| Pageable | Defines attributes used for result set paging | Apply to a GET method that supports pagination |
| Sortable | Defines attributes used for result set sorting | Apply to a GET method that supports sorting |
| Trackable | Defines a header for supplying tracking information | Apply to any endpoint for end-to-end traceability |
Data types
| Type Name | Description | Typical Usage |
|---|---|---|
| BasicResponse | Defines a generic API response structure, which includes an overall status code and zero or more result messages | Use for POST and other endpoints that do not return a business data response |
| ResultMessage | Defines a generic message structure for use in API responses | Use to incorporate standard messages into non-standard responses |
Usage
To use one or more of these resources in your API definition, first add this library as an Exchange dependency to your Design Center project so that you can import it into your main RAML file. For example:
uses:
GlobalResources: exchange_modules/<groupid>/accelerator-global-resources/2.0.2/accelerator-global-resources.ramlYou can then add the appropriate trait(s) to your endpoints as follows:
/health:
description: Test connectivity to this API and back-end resources
get:
is: [ GlobalResources.HealthResponse ]
/accounts:
description: Find one or more accounts matching a given set of criteria
is: [ GlobalResources.ErrorResponses ]
securedBy: [ GlobalResources.BasicAuth ]Notes
If you update the version of the Exchange dependency you will need to manually update all file path references.