... | ... | @@ -36,6 +36,7 @@ All API endpoints are Coldbox events in handlers extending **BaseHandler**. Each |
|
|
5. [REST Convention](#api-rest-convention)
|
|
|
6. [Validation](#validating-api-requests)
|
|
|
7. [Function](#api-endpoint-function)
|
|
|
8. [Conventions (Expand)](#api-endpoint-conventions)
|
|
|
|
|
|
### API Endpoint Authentication
|
|
|
|
... | ... | @@ -153,6 +154,22 @@ This approach leverages `constraints` on a domain object, but pulls those constr |
|
|
|
|
|
The content of a single Coldbox event should be as short as possible to achieve the desired results. This is an area of concern for **DRY**: If there is a significant amount of business logic going on, that should take place in a model or service layer and not the API handler, unless it is absolutely, positively certain that the business logic will only ever be used in one place. Even then, envision a subsequent version of your API: if you wanted to take your endpoint and update it from **v1** to **v2**, you would ideally only concern yourself with writing the changes in business logic in the **v2** endpoint. If you would have to replicate a lot of unchanged code from your **v1** handler, probably that portion should have gone into a service layer (whether on a model object or a separate service object).
|
|
|
|
|
|
## API Endpoint Conventions
|
|
|
|
|
|
### Expand
|
|
|
|
|
|
As of October 2020, the inLeague API supports an **expand** array parameter to all requests. The convention is borrowed from Stripe's [Expanding Requests](https://stripe.com/docs/api/expanding_objects) feature as a mechanism for an API consumer to request additional data from an endpoint without having to establish a whole new endpoint.
|
|
|
|
|
|
To enable an expandable field, see `qInvoiceInstance.cfc` as an example. The `expandable` property on `this.memento` contains an array of possible expandable items. When calling for the memento via `.asMemento()` or `.getMemento()`, it is necessary to specify an `includes` argument, as with the `invoice.cfc` `view` handler:
|
|
|
|
|
|
```
|
|
|
invoice.getMemento( includes = invoice.getExpandedIncludes( rc.expand ) )
|
|
|
```
|
|
|
|
|
|
The default behavior of `getExpandedIncludes()` is to append any values from the `expand` parameter to the `defaultIncludes` of the memento. If you do not want to use the `defaultIncludes`, you can specify a second argument called `includes` to `getExpandedIncludes()` and it will use that value in place of the defaultIncludes.
|
|
|
|
|
|
`getExpandedIncludes()` is defined on the inLegaue base Quick entity.
|
|
|
|
|
|
Remember: **Fat models, skinny handlers.**
|
|
|
|
|
|
## Documenting API Endpoints
|
... | ... | |