REST modeling vocab

Question

I am working on a vocab which should describe REST applications, but I cannot find the proper word for a term.

resource
    operations
        command/query extends operation
            name
            parameters
                parameter
                    name
                    type
                    ...
    properties
        property
            name
            type
            ...
representation
    controllers
        controller
            operation -> resource.operation
            inputs
            ...
    *s
        *
            property -> resource.property
            type
            transformation (e.g., datetime to iso8601)

What I am looking for is the *. According to one of the articles about REST, the REST services provide abstract controllers and abstract views in the hypermedia representations of the resources.

I am not sure, should I call the * as view, or are there better words? By controller this analogy works perfectly, I can have different types of controllers:

SearchForm -> bound to Query
Link -> bound to Query
UpdateForm -> bound to Command

and so on...

Be aware that this is not the implementation, this is the vocab of the meta data which can describe every REST service. For example by a HAL+JSON response can be described this way:

{ //representation
    "_links": { // controllers
        "self": { "href": "/product/987" }, // a link
        "upsell": [
            { "href": "/product/452", "title": "Flower pot" }, // a link
            { "href": "/product/832", "title": "Hover donkey" } // a link
        ]
    },
    // *s
    "name": "A product", // a *
    "weight": 400 // a *
}

Conclusion about the usage of REST vocabs:

I thought about this a lot, and I think this kind of vocabs has no general use on server side, because the resources do not necessarily exist on server side as aggregates, entities, etc... REST is just a delivery method, which has nothing to do with the domain model, so we cannot use for example a resource graph to generate business logic classes, and vica-versa. REST is connected to the surface of the business logic (as every delivery method does), so for example by CQRS we can easily bind Command or Query instantiation to REST operations, but we cannot bind Aggregates to REST resources. REST resources can be part only of DTOs sent to (or received from) the business logic...

resource -> cannot be bound to any business logic class, any aggregate, etc...
    operations
        command/query -> can be bound to CQRS Command/Query (DTO) classes
            name
            parameters -> can be bound to CQRS Command+Query class properties
                parameter
                    name
                    type
                    ...
    properties -> cannot be bound to properties of business logic classes, aggregates
        property
            name
            type
            ...

I saw ppl who are confusing these two terms, and try to use REST resources to describe the business logic of their applications. By very simple applications this may work, but by more complex applications this fails, because it is much harder to generate a complex application from a config which describes only a delivery method of the application...

So it is pointless to use this kind of vocabs in order to generate server side code. Okay, but what can we use them for?

We can use them in REST to add meta-data to the hypermedia response. For example we can use them in templates or add them in builders. This meta-data can be very useful to generate both general REST browsers and application specific REST clients. For example a myApp:operation can be bound to a rest:controller instance. By knowing the rest:controller class, the REST client can display a link or a form, and by knowing the myApp:operation the REST client can display a link, specific to that operation. For example by a webshop:addToCart operation it can display a cart icon as a submit button, etc... Using semantic REST APIs with RDF responses (for example JSON-LD), is a preferable alternative of using vendor specific MIME types in the hypermedia response.

score 0 · Accepted Answer · answered May 15 '14 at 02:04

I decided to use the controller and view words.

I though of these words as reserved by a full application context, because the REST hypermedia returns only abstract controllers and abstract views, and the real controller and view classes are on the client side.

However in a narrower, server only context these words are appropriate, because the REST API is related to the presentation layer (or delivery or ui port depending on the chosen architecture) of the server side application.

REST modeling vocab

Conclusion about the usage of REST vocabs:

1 Answers1