Hide Comments

The request and response elements define the Request and Response Messages, respectively, for a Method.  The message specification includes the message body, or payload, message parameters, and (for a response message) the status code.  The message payload is specified as a Data Structure realization; either the same realization as the containing resource, a different resource, or a different Data Structure altogether.

Syntax

Message with Empty Payload

request | (response [statusCode <response-code>])

[mediaTypes <media-types>]

[<message-param>]...

[<example> | <external-example>]...

 

Message with Resource-Defined Payload

(request | response) [~with] ( (this [[~resource] <resource-realization>]) | ([~resource] <resource-realization>) )  [statusCode <response-code>]

[mediaTypes <media-types>]

[<message-param>]...

[<example> | <external-example>]...

 

Message with Data Structure Realization as Payload

(request | response) [~with] type <data-structure>  [statusCode <response-code>]

[<property-set>]

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

[mediaTypes <media-types>]

[<message-param>]...

[<example> | <external-example>]...

Examples

method GET getPersonObject

// Empty request

request

// response with a representation of the current resource

response with this PersonObject statusCode 200

 

// Request with empty message payload and optional parameters

method GET getPersonCollection

request

param nameContains of type string in query

param inCountry of type string in query

param includeInactive of type boolean in query

 

// Request with a representation of the current resource

method PATCH updatePersonObject

request with this PersonObject

 

// Request with a representation defined by another resource

method GET searchPersonCollection

request with resource SavedSearchObject

 

// Request with a specialized data structure realization

method POST addPersonToCollection

request with type Person

with all properties including

firstName!

lastName!

excluding

taxpayerID

referenceEmbed > addresses

Parameters

Name

Type

Description

request

keyword

Identifies the message as a request. A Method MAY define at most one request.

response

keyword

Identifies the message as a response. A Method MAY define any number of responses.

this

keyword

A special case of a resource-defined message payload, where the payload is a representation of the object instance bound to the resource at runtime.

 

Whereas a message specifying the name of the containing resource, but not specifying this, could represent any runtime instance of the resource; using this asserts that the message represents the same object instance as the resource on which the Method is invoked.

 

When this is specified, the <resource-realization> parameter MAY be specified for clarity, but is optional. If <resource-realization> is specified following this, it MUST be a valid qualified or unqualified reference to the containing resource.

<resource-realization>

QName(Collection Resource or Object Resource)

Identifies a resource that defines the message payload model.  The runtime message payload will contain a representation of that resource.

 

More precisely, it will contain an instance of the Data Structure bound to the resource, and conforming to the realization specified (explicitly or implicitly) in the resource.

<data-structure>

QName(Data Structure)

Identifies a Data Structure that defines the message payload model. The runtime message payload will contain an instance of the Data Structure, conforming to the realization specified (explicitly or implicitly) in the message definition.

<response-code>

integer

A valid HTTP response code, as defined in RFC 2616, section 10.  <response-code> MAY be specified only for response messages, not for requests.

<media-types>

List(SName(Built-in Media Type)or QName(User-defined Media Type))

A delimited list of references to media types allowed in this message.  Overrides media types specified at the resource level.

Child Elements

Name

Topic

Description

<property-set>

Property Set

An optional Property Set, used to customize the realization of the specified <data-structure>.

<reference-link>

Reference Link

An optional Reference Link, used to realize a reference in the <data-structure> as a hyperlink.

<reference-embed>

Reference Embed

An optional Reference Embed, used to realize a reference in the <data-structure> as an embedded object..

<message-param>

Message Parameter

Defines a parameter carried in the header or query string, separate from the message payload.

<example>

Example

Specifies an in-line example of the message, for documentation and testing.

<external-example>

Example

References an externally defined example of the message, for documentation and testing.

Parent Elements

Method

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