Building the best open source project collaboration software.
" }, "_links": { "self": { "href": "/api/v3/projects/14", "title": "OpenProject" } ... } }, "status": { "_type": "Status", "id": 7, "name": "confirmed", "isClosed": false, "color": "#FFA8A8", "isDefault": false, "isReadonly": false, "defaultDoneRatio": null, "position": 6, "_links": { "self": { "href": "/api/v3/statuses/7", "title": "confirmed" } } } }, } ``` In this linked example, only the `status` and `project` links and embedded resources were kept, as well as some work package properties removed. ## HalResourceService On to loading the JSON resources from the API and turning them into usable class instances. This is the job of the the [`HALResourceService`](https://github.com/opf/openproject/tree/dev/frontend/src/app/modules/hal/services/hal-resource.service.ts). It has two responsibilities: 1. It uses the Angular `HTTPModule` for performing API requests to the APIv3 2. It turns the responses of these requests (or HAL JSON generated in the frontend) into a HAL resource class ### Performing requests against HAL API endpoints The service has HTTP `get`, `post`, `put`, etc. methods as well as a generic `request` method that accept an URL and params/payload, and respond with an observable to the JSON transformed into a HAL resource. ### Error Handling For errors returned by the HAL API (specific error `_type` response in the JSON) or when erroneous HTTP statuses are being returned, the `HALResourceService` will wrap these into `ErrorResources` for identifying the cause and potentially, additional details to present to the frontend. This is used for example when saving work packages and validation errors occur. The validations are being output in details for individual attributes. ## Linked HAL resources The `_links` entries of a HAL resource can have a `url`, `method`, and `title` property. They can also be `templated` if the link needs to be filled out by the frontend (e.g., to set a related ID to pass into it). In the process of building the HAL resource, action `_links` objects are being turned into resources themselves: - Either into a `HALResource` class themselves if the linked object is retrieved via `GET` from the API - Or into a `HalLink` class instance to perform an action link. The [`HalLink`](https://github.com/opf/openproject/tree/dev/frontend/src/app/modules/hal/hal-link/hal-link.ts) class is a wrapper around the `HalResourceService#request` method to call the action. This way, the action links can be called automatically by calling, e.g., `workPackage.update()` to request the form link with the URL defined in `_links.update.href`. For linked resources such as `_links.project`, this will result in the `workPackage.project` property being a HALResource that can be loaded from the API with `workPackage.project.$load()`. This will modify the project resource in the work package, mutating it in place. ```typescript // Building source from object here, instead of loading from the API for demo purposes const source = { id: 1234, _type: 'WorkPackage', _links: { project: { href: '/api/v3/projects/1', title: 'Demo Project' } } }; // HalResourceService looks up the `_type` to return the correct resource type const wp:WorkPackageResource = halResourceService.createHalResource(source); // Project link was turned into a resource console.log(wp.project.href); // /api/v3/projects/1 // The resource is not embedded, thus not loaded console.log(wp.project.$loaded); // false // The name property is available from the title attribute console.log(project.name); // Demo Project // Explicitly load the HAL resource const project = await wp.project.$load(); console.log(project.href); // /api/v3/projects/1 console.log(project.name); // Demo Project console.log(wp.project.$loaded); // true ``` On first glance, it might look nice to be able to `$load()` the embedded project on the fly and use the returning promise. However, this request will not be cached anywhere, thus loading the same project on multiple work packages will result in multiple requests. Also, the `workPackage` state will be constantly mutated whenever these requests happen. You will always have to check whether the resource was loaded. Instead of explicitly loading embedded resources, the frontend now usually uses a `CacheService` to load and cache a resource of a specific type by its href. For example, for the project, there is a `ProjectCacheService#require(href)` method that will ensure a project is loaded, or fetched from cache and returns a promise to use. This will no longer mutate the work package resource. However, there are still use cases where `.$load()` is used and the resource is mutated. ## HAL resource builder In order to turn the JSON properties from `_embedded` and `_links` into writable properties on the HAL resource, there is a set of functions called the [`HAL resource builder`](https://github.com/opf/openproject/tree/dev/frontend/src/app/modules/hal/helpers/hal-resource-builder.ts). It will take care of: - Maintaining a `$source` property which is the pristine JSON response from the API. - Mapping the properties under `_links` into `$links` property with `HalLinks` that can be called in the application. `e.g., workPackage.$links.update()` will call the API to the URL behind that link. - Mapping the properties under `_embedded` into `$embedded` and turning each of these into their own `HalResource` instance. - It definers setters to all properties of the HAL resource to modify the `$source` object. For example, if you have a link `_links.project` in your JSON, you can override the project used for the resource with `resource.project = projectResource` or `resource.project = { href: '/api/v3/projects/1234' }`. This will modify the `$source` object. The frontend doesn't really use this anymore due to it boiling down to a large mutable object. Instead, we use `ResourceChangesets` to modify resources and save them. [Click here to see the separate concept on them](../resource-changesets). ## 🔗 Code references - [`HALResourceService`](https://github.com/opf/openproject/tree/dev/frontend/src/app/modules/hal/services/hal-resource.service.ts) for loading and turning JSON responses into HAL resource classes - [`halResource.config.ts`](https://github.com/opf/openproject/tree/dev/frontend/src/app/modules/hal/services/hal-resource.config.ts) for identifying what types in the JSON response and its members/links are being turned into which classes. - [`HalResource`](https://github.com/opf/openproject/tree/dev/frontend/src/app/modules/hal/resources/hal-resource.ts) the base HAL resource class - [`HAL resource builder`](https://github.com/opf/openproject/tree/dev/frontend/src/app/modules/hal/helpers/hal-resource-builder.ts) used for wiring up the links and embedded JSON properties into members of the HAL resource classes ## Discussions - Due to the dynamic properties of the HAL resource, it traditionally has an index map to `any` which is the source of many typing issues and in turn, quite a number of bugs: https://github.com/opf/openproject/blob/76823ca58179a87afbb5fc0925c3453780dec381/frontend/src/app/modules/hal/resources/hal-resource.ts#L56-L60 - The way HAL resources work by embedding and allowing to load