Hide Comments

The collectionResouce element describes how a collection of a particular data type is exposed by the API and how it may be accessed. Collection Resources are bound to a Data Structure from an accessible Data Model.

Syntax

[default] collectionResource <resource-name> [~bound ~to] type <bound-data-structure>

[<uri>]

[<secured>]

[<property-set>]

[<reference-embed> | <reference-link>]...

[<link-descriptor-definition>]...

[<media-types>]

[<method>]...

[<example>]...

Examples

default collectionResource PersonCollection type Person

URI people

secured by

 auth.Basic

// Combined Property Set: uses including and excluding keywords

with all properties

including

taxpayerID!

exluding

otherNames

// Reference treatment: embedded

referenceEmbed > addresses

linkDescriptor MyResourceLink

firstName

lastName

mediaTypes

application/json

method GET getPersonCollection

method POST postPersonCollection

example ''' Any text can go here '''

example ''' But this should show what a legal message from this resource should look like '''

Parameters

Name

Type

Description

default

keyword

Explicitly designates this Collection Resource as the default hyperlink target for references to the bound Data Structure.  See Automatic Linking and Embedding for a full explanation.

<resource-name>

Name

The Name of this resource. Unique in the context of this Resource API.

<bound-data-structure>

QName(Data Structure)

A reference to the underlying Data Structure bound to this Collection Resource.

Child Elements

Name

Topic

Description

<uri>

URI

The URI of this resource, relative to the baseURI of the containing Resource API.

<secured>

Secured

Describes how this resource is secured.

<property-set>

Property Set

Part of the default realization of this resource.

<reference-embed>

Reference Embed

Part of the default realization of this resource.

<reference-link>

Reference Link

Part of the default realization of this resource.

<link-descriptor-definition>

Link Descriptor Definition

A reusable descriptor for use in Reference Links from other resources.

<media-types>

Media Types

The default media types supported by this resource.

<method>

Method

An HTTP method definition.

<example>

Example

An example of what valid data passing to/from this resource should look like.

Parent Elements

Resource API

Discussion

Linked vs. Embedded Realization

A Collection Resource represents a list of references to its bound Data Structure.  These references may be realized as embedded representations, or as hyperlinks, according to the following rules:

If the Collection Resource specifies a Property Set, specifies one or more Reference Links, or specifies one or more Reference Embeds:
oThe Collection Resource is realized as a list of embedded objects, following the realization model specified in the Property Set, Reference Links and/or Reference Embeds.
If the Collection Resource does not specify a Property Set and does not specify any Reference Links or Reference Embeds:
oIf there is a Default Object Resource for the bound Data Structure in scope, the Collection Resource will be realized as a list of hyperlinks targeting the Default Object Resource.
oIf there is not a Default Object Resource for the bound Data Structure in scope, the Collection Resource will be realized as a list embedded objects, using the default realization rules.

Created with Help & Manual 6 and styled with Premium Pack Version 2.51 © by EC Software