resources

Resources

resource

The RIM language uses the resource nomenclature to define a container for an entity or multiple entities. e.g. the example resource below represents a collection of Message entities.

resource messages {
	type: collection
	entity: Message
	view: GETHelloMessage
}

A resource MUST be given a unique name, it MUST provide a view command or workflow, and it MUST represent either an item or a collection of an entity.

To be considered valid, a RIM definition MUST define exactly one initial resource; all other resources MUST have at least one transition from another resource.

view

A command or workflow that will be executed when a safe transition to a state is issued.

resource messages {
	type: collection
	entity: Message
	view: GETHelloMessage
}

actions

A list of command or workflow, separated by ,, that will be executed when an unsafe transition to a state is made.

resource messages {
	type: collection
	entity: Message
	actions [ GETHelloMessage, UpdateMessage ]
}

commandproperties

A resource MUST define a command that will be executed when the resource is dereferenced by a User-Agent or client, see view or actions type of commands. These commands MAY define properties that set or override any properties already defined on the command. They MAY define a cache which hints how long (in seconds) the resource fetched by that command can be considered valid.

resource messages {
	type: collection
	entity: Message
	view: GETHelloMessage {
		properties [ greeting="Hey" ] cache 300
	}
}

relations

A list of relations that MAY be used in any links to this state. Accepts a relation reference or a string which can be used as fully qualified name.

resource messages {
	type: collection
	entity: Message
	view: GETHelloMessage
	relations [ collection, "http://www.myorg.com/rels/profile" ]
}

path

A resource MAY define a path to this conceptual resource; this will form the hierarchical part of the logical uri at runtime see rfc3986

resource messages {
	type: collection
	entity: Message
	view: GETHelloMessage
	path: "/messages"
}

type (deprecated at 0.4.0, see trait)

A resource can define one of two types of resource; they are either an item or a collection

item

An individual.

collection

A collection of individuals.

initial resource

An initial resource is a special resource state that identifies a logical entry point to the interaction model. It MAY be used by a runtime container to understand the starting point(s) of the resource graph, a runtime container MAY only bind resources to paths when they exist in the graph from this initial starting point.

initial resource Root {
	type: item
	entity: ServiceDocument
	view: GETServiceDocument
}

A set of resource interaction models MUST define one initial resource.

exception resource

An exception resource is a special resource state used to catch interaction errors for resources which do not have an onerror handler.

exception resource AirlineException {
	type: item
	entity: AirlineError
	view: GETException
}

trait

A trait defines a class of resource and the path parameters / query parameters that it will accept. NB - This feature replaces item and collection types.

rim Common {
	trait collection {
		description: "Declares a type of resource that contains a collection of entities"
		queryParameter page {
			name: "page"
			description: "Supply a positive integer to request a subset of the Entities in the Collection."
		}
		queryParameter pageSize {
			name: "pageSize"
			description: "Supply a positive integer to request a limited number of rows be returned."
		}
	}

	trait item {
		description: "Declares a type of resource that contains an individual entity"
		identifier pathParameter id {
			path: "/{id}"
			description: "An identifier path parameter, and will form the id part of the logical uri"
		}
	}
}

extends

Using the extends keyword, a new resource can be defined that adds traits, relations, transitions or overrides any attribute of another resource. This can be useful when you want to define a fixed set of resources to be used as 'data services' and a separate set of resources to be used as 'interaction services'.

rim Notes {

	//
	// Interaction Services that guide you to creating new Note's from the root or the collection
	//
	resource root {
		description: "The main entry point for our hypermedia User-Agents"
		GET -> new_notes
		POST -> newNote
	}
	resource new_notes extends notes {
		POST -> newNote
	}
	resource newNote {
		type: item
		entity: Note
		relations [{
			fqn: "http://www.myorg.com/rels/new"
			description: "POST to this resource and you will receive a populated Note in the response payload.  The Note will be populated with the next ID from a stack.  This resource can be safely thrown away without an associate PUT to create the Note"
		}]
		actions [ CreateNextNote ]
		path: "/notes/new"
		PUT -> note
	}

	//
	// Data Services
	//
	resource notes {
		type: collection
		entity: Note
		view: GETNotes
		path: "/notes"
		GET *-> note
	}
	resource note {
		type: item
		entity: Note
		view: GETNote
		path: "/notes/{noteID}"
	}

}

onerror

The onerror keyword declares an error handler which enables resources to delegate the error handling to other resources.

resource flights {
	type: collection
	entity: Flight
	view: GETEntities
	path: "/Flight"
	GET *-> flight {
		parameter id {
			value: "{flightID}"
		}
	}
	onerror --> flightError
}

resource flightError {
	type: item
	entity: FlightError
	view: GETFlightError
}

The result of executing the view action on the error resource will be returned as the response of the current request. It may be desirable to return a link to an error details resource in case the current request should return something else such as e.g. a summary of errors.

resource flights {
        ...
	onerror --> flightErrorSummary
}

resource flightErrorSummary {
	type: item
	entity: FlightErrorSummary
	view: GETFlightErrorSummary
	GET -> flightErrors
}

resource flightErrors {
	type: item
	entity: FlightError
	view: GETFlightErrors
}

The additional complexity involved in this step is that a user will have to access flightErrors with a separate request. It is therefore the responsibility of the GETFlightErrorSummary command to store the errors details and GETFlightErrors to retrieve it from intermediate storage. This storage area could be the resource manager, an in-memory database or a cache.