|
<< Click to Display Table of Contents >> Adding Collection and Index Resources |
  
|
|
<< Click to Display Table of Contents >> Adding Collection and Index Resources |
|
To recap, we have now defined a basic RESTful API, with two completed resource definitions each bound to a data structure:
| • | The TaxFilingObject resource is bound to a single data structure of type TaxFiling. |
| • | The PersonObject resource is bound to a single data structure of type Person. |
These two resources have demonstrated some basic capabilities of RepreZen™ API Studio. However, a real API will need additional resources to hold collections of each major data type. Additionally, a recommended practice for REST APIs is that a single resource should serve as the entry point, and should provide access to the other resources either directly or indirectly.
In this section, then, we'll add collection and index resources to complete the API definition.
Defining a collectionResource
In RepreZen API Studio, we have seen that an objectResource represents a single object type resource of a given data type. However, when we want a list of objects of a given data type, we use a collectionResource instead.
| • | The collectionResource can provide the full set of objects the given data type, or a qualified subset identified by parameters. |
| • | In the example API we will define collectionResource resources to provide the full list of TaxFiling and Person objects. |
Defining collectionResources for TaxFiling and Person
We'll now add collectionResource definitions for the data types defined in our dataModel.
| 1. | First, we'll complete the generated collectionResource we have so far been ignoring, currently called TaxBlasterCollection: |
| a. | Rename this to TaxFilingCollection using the rename refactoring (Alt+Shift+R). The type, TaxFiling, is already correct. |
| b. | Change the URI to taxfilings. |
| c. | Change the GET and POST method names to getTaxFilingCollection and postTaxFilingCollection respectively. |
| 2. | Now we'll add a collectionResource named PersonCollection of type Person with the URI people after TaxFilingCollection. Place the cursor on the bottom right hand corner of TaxFilingCollection, press Enter and then Backspace twice: |
| 3. | Press Ctrl-Space for Code Assist and select the Collection Resource template: |
| 4. | Fill in the template with the resource name PersonCollection, type Person, and the URI people. Use the Tab key to advance through the template, and press Enter when you're done. |
| 5. | Finally, we'll add documentation comments as shown below so that the completed code looks as follows: /** The list of Tax Filings visible to the authorized user. */ collectionResource TaxFilingCollection type TaxFiling URI taxfilings mediaTypes application/xml method GET getTaxFilingCollection request response TaxFilingCollection statusCode 200 method POST postTaxFilingCollection request TaxFilingCollection response statusCode 200 response statusCode 400 /** The list of TaxBlaster users. The results will vary in membership and level of detail, depending on your access privileges.*/ collectionResource PersonCollection type Person URI people mediaTypes application/xml method GET getPersonCollection request response PersonCollection statusCode 200 method POST postPersonCollection request PersonCollection response statusCode 200 response statusCode 400 |
| 6. | Save the RAPID model. |
Defining an Index Resource
For the entry point, we'll define an Index data type, and a corresponding IndexResource.
| 1. | In the dataModel, add an index structure as follows, at the beginning, before TaxFiling. /** The supporting data type for the Index resource. Not meaningful as a business entity, but required to support a single point of entry. */ structure Index people : reference to Person* taxFilings : reference to TaxFiling* The index data type contains references to sets of Person and TaxFiling data obtainable via the collectionResource entries we just defined. |
| 2. | Now, in the resourceAPI, let's define an index objectResource as follows, at the top, before TaxFilingObject: /** The Index Resource is the entry point to the TaxBlaster API. To minimize coupling, consuming applications should start here, and follow the links to related resources. */ objectResource IndexResource type Index URI /index mediaTypes application/xml method GET getIndexResource request response IndexResource statusCode 200 method PUT putIndexResource request IndexResource response statusCode 200 response statusCode 400 |
Sanity checking our rapidModel
We now have a semi-complex API, and we can sanity check this with the Diagram View to see if what we've built looks right. If we've done everything correctly, and got our references right, then the API diagram should now look like the one below.
The entry point URL for the API is /index. The response from this will return references to collections of Persons and TaxFilings obtainable via the URLs /people and /taxfilings respectively, and these collections will themselves contain references (URLs) to individual Person and TaxFiling object resources.
| 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. |