Open APIs

 View Only

About TM Archetypes definitions vs API best practices

  • 1.  About TM Archetypes definitions vs API best practices

    TM Forum Member
    Posted Aug 17, 2018 15:03
    ​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 Tutorial

    TM 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.

    1. 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
    2. 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
    3. 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
    4. 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.
    ------------------------------