|
<< Click to Display Table of Contents >> Customizing Reference Links |
  
|
|
<< Click to Display Table of Contents >> Customizing Reference Links |
|
Previously, we added two collection resource definitions and an index resource. In this section, we'll examine some other capabilities of referenceLinks.
Adding an Explicit referenceLink from TaxFilingObject to PersonObject
By default, references between structures in the data model are represented as reference links between resources. For example, in our code, the TaxFiling type has a taxpayer property. This is represented as a reference to a resource bound to the Person data type. If we look in the diagram we'll see this reference depicted as follows, with the red link going off to the PersonObject resource:
Such reference links are 'naked' hyperlinks. They don't carry any special information describing the nature of the relationship, and they don't give the API consumer any of the essential properties of the target object. The API consumer has to traverse the hyperlink to inspect the target object's values.
For some API clients this is not very efficient. For example, a few key properties of the target object may be enough to populate a summary table in a web page. If the end user needs more information they can click a link in each row to get it. But the client application should not have to traverse those links ahead of time just to build the table.
To handle this kind of situation we will use the concept of a decorated hyperlink which has some key fields along with a hyperlink that can be traversed when more details are required. To demonstrate this we'll decorate the taxpayer hyperlink in the TaxFilingObject resource with some properties from Person, the target data type.
| 1. | In theTaxFilingObject, add an explicit referenceLink specifying the reference property taxpayer and the targetResource PersonObject: /** An individual Tax Filing record, accessed by its ID */ objectResource TaxFilingObject type TaxFiling URI taxfilings/{id} /** filingID of the requested TaxFiling */ required templateParam id property filingID referenceLink > taxpayer targetResource PersonObject mediaTypes application/xml method GET getTaxFiling response TaxFilingObject statusCode 200 response statusCode 404 Take a look at the diagram for TaxFilingObject that we looked at before and note that it has not changed. This is because all we have done so far is add code that makes the implicit naked referenceLink explicit. |
| 2. | We can now complete the referenceLink by adding the targetProperties id and lastName so that it becomes a 'decorated hyperlink', like this: referenceLink > taxpayer targetResource PersonObject targetProperties firstName lastName |
| 3. | Save the code, wait for the diagram to regenerate and expand the compartments in TaxFilingObject to see the reference link details: |
Note: this decoration is *not* done in the dataModel definition but in the API - the context in which the dataModel is being used. The dataModel remains untouched by this change. This point is crucial to understanding RepreZen™ API Studio approach. We can define services based on reusable, canonical data models because we are able to adapt these models to the particular needs of each service context. This creates the conditions in which data standardization can emerge.
The decorated hyperlink is a simple example of how we can customize the realization of data models in our API so that our resources expose the data in a way that suits our particular purpose. We will explore this subject in more depth later on.
| Copyright © 2016 ModelSolv, Inc. All rights reserved. RepreZen and RAPID-ML are trademarks of ModelSolv, Inc. Swagger is a registered trademark of SmartBear Software, Inc. RepreZen API Studio is not associated with nor endorsed by SmartBear Software, Inc. |