Hi,
TM Forum give definition about Collection, Managed and Task Resource
From the REST API best practices four (4) archetypes categories are described (document, collection, store and controller).
My understanding of terms used by TM and correspondence with the API TutorialTM Collection = API archetype collection
TM Managed = API archetype document
TM Task = API archetype controller
TM Forum does not define the archetype store
AM I aligned?
REST Resource Identifier (URI) Naming - REST API Tutorial
For more clarity, let's divide the resource archetypes into four categories (document, collection, store and controller) and then you should always target to put a resource into one archetype and then use it's naming convention consistently. For uniformity's sake, resist the temptation to design resources that are hybrids of more than one archetype.
-
document
A document resource is a singular concept that is akin to an object instance or database record. In REST, you can view it as a single resource inside resource collection. A document's state representation typically includes both fields with values and links to other related resources.
Use "singular" name to denote document resource archetype.
http://api.example.com/device-management/managed-devices/{device-id}
http://api.example.com/user-management/users/{id}
http://api.example.com/user-management/users/admin
-
collection
A collection resource is a server-managed directory of resources. Clients may propose new resources to be added to a collection. However, it is up to the collection to choose to create a new resource, or not. A collection resource chooses what it wants to contain and also decides the URIs of each contained resource.
Use "plural" name to denote collection resource archetype.
http://api.example.com/device-management/managed-devices
http://api.example.com/user-management/users
http://api.example.com/user-management/users/{id}/accounts
-
store
A store is a client-managed resource repository. A store resource lets an API client put resources in, get them back out, and decide when to delete them. A store never generates new URIs. Instead, each stored resource has a URI that was chosen by a client when it was initially put into the store.
Use "plural" name to denote store resource archetype.
http://api.example.com/cart-management/users/{id}/carts
http://api.example.com/song-management/users/{id}/playlists
-
controller
A controller resource models a procedural concept. Controller resources are like executable functions, with parameters and return values; inputs and outputs.
Use "verb" to denote controller archetype.
http://api.example.com/cart-management/users/{id}/cart/checkout
http://api.example.com/song-management/users/{id}/playlist/play
***************************************
From Frameworx Specification REST API Design Guidelines Part 1
API Resource Archetypes
The following section describes the resource archetypes supported by the TMF REST APIs
A REST API is composed of 3 distinct resource archetypes and should align each resource to just one of these:
1. Collection Resource – server managed collection of resources. In the TMF REST API Design Patterns collections are anonymous. A resource with no identifier represents the resource collection (matching the resource type). Example: troubleTicket, productOrder
2. Managed Resource – e.g. a database record or an object instance–. Its representation includes: fields with values and links to related resources. Can have child resources, of different resource types. Client can create, query, update and delete resources. Example: trouble Ticket, productOrder
3. Task Resource – resources that are executable functions – with associated input and output parameters. Necessary where the required action cannot be mapped to standard CRUD methods. Tasks play the role of Controllers in Rails. E.g. ProductOfferingQualification, ServiceQualification
------------------------------
Benoit Le Nabec
CGI Info Systems Management Consulting Inc.
------------------------------