Thanks a lot Mike for the detailed and very valuable review and comments.
Indeed, single-value enums are the way to fix parameters. It worked for swagger-ui to pass query params in the path element but I agree this is not standard. I'll update the sample app.
I'll also update the sample to output the responses field. Here also, it worked with swagger-ui but better be fully spec compliant !
I'll change "verb" to "method" which is more correct (although I've yet to see an HTTP method which is not a verb 😄).
But I think RMM REST level 2 APIs are still RPC. GET /api/users/ conveys the exact same semantics as getUsers. Separating the resource and the verb into distinct fields of the request doesn't change that. The best proof is that it's possible to generate client SDKs that do the translation for a given programming language. Another proof that it's easy to replace these APIs any time with another RPC (gRPC, SOAP, etc...). And I think that was the point of Fielding's rant. Note that I don't say RPC is inferior (I love gRPC), just that it's not REST as defined by its author. Anyway, I know that the battle is lost and that REST level 2 is now REST. So that's just historic details. As we say, "usage is law".
Thanks for the reply, as I said I do find this approach interesting and worthwhile. I blogged about returning partial OAS documents here: dev.to/mikeralphson/the-hypermedia...
If you use single value enums, won't you hit the problem of clashing (identically-defined) pathItem keys? How would you distinguish them? Hence my suggestion to dynamically build the enum lists based on allowable values for the parameter (maybe within a page range etc to prevent the list being too large).
Fielding (2000) says: (In section 6.5.2 'HTTP is not RPC') "What makes HTTP significantly different from RPC is that the requests are directed to resources using a generic interface with standard semantics that can be interpreted by intermediaries almost as well as by the machines that originate services. The result is an application that allows for layers of transformation and indirection that are independent of the information origin, which is very useful for an Internet-scale, multi-organization, anarchically scalable information system. RPC mechanisms, in contrast, are defined in terms of language APIs, not network-based applications." For example, HTTP APIs are generally cacheable, RPC mechanisms generally are not.
"HEAD" and "OPTIONS" are the two obvious non-verb standard HTTP methods. :)
If you use single value enums, won't you hit the problem of clashing (identically-defined) pathItem keys?
Yes. That's a problem of OAI using a map for pathItems. I could have chosen to directly reference an array of pathItems in controls but then it wouldn't be 100% compatible with existing tools and libs (eg. swagger-ui) which is I think a strength ot the OHM format. Eg in the paging implementation, you can have 2 links with the same path+method (eg. "first page" and "previous page"). I worked around it by setting a fragment in the path to distinguish the 2 affordances. This fragment being ignored server-side. The problem of an enum list is that if you have several params, you don't know which combination of enum is allowed. And I don't see how to associate an affordance (eg. "first page") to an enum value.
I opened github.com/cbornet/ohm/issues/1 to track this issue.
Fielding (2000) says: (In section 6.5.2 'HTTP is not RPC')
If Roy says it, I guess this is it ... 😅 . But we still call procedures remotely...
"HEAD" and "OPTIONS" are the two obvious non-verb standard HTTP methods. :)
I should get some sleep 🤦...
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
Thanks a lot Mike for the detailed and very valuable review and comments.
Indeed, single-value enums are the way to fix parameters. It worked for swagger-ui to pass query params in the path element but I agree this is not standard. I'll update the sample app.
I'll also update the sample to output the responses field. Here also, it worked with swagger-ui but better be fully spec compliant !
I'll change "verb" to "method" which is more correct (although I've yet to see an HTTP method which is not a verb 😄).
But I think RMM REST level 2 APIs are still RPC.
GET /api/users/conveys the exact same semantics asgetUsers. Separating the resource and the verb into distinct fields of the request doesn't change that. The best proof is that it's possible to generate client SDKs that do the translation for a given programming language. Another proof that it's easy to replace these APIs any time with another RPC (gRPC, SOAP, etc...). And I think that was the point of Fielding's rant. Note that I don't say RPC is inferior (I love gRPC), just that it's not REST as defined by its author. Anyway, I know that the battle is lost and that REST level 2 is now REST. So that's just historic details. As we say, "usage is law".Thanks for the reply, as I said I do find this approach interesting and worthwhile. I blogged about returning partial OAS documents here: dev.to/mikeralphson/the-hypermedia...
If you use single value enums, won't you hit the problem of clashing (identically-defined) pathItem keys? How would you distinguish them? Hence my suggestion to dynamically build the enum lists based on allowable values for the parameter (maybe within a page range etc to prevent the list being too large).
Fielding (2000) says: (In section 6.5.2 'HTTP is not RPC') "What makes HTTP significantly different from RPC is that the requests are directed to resources using a generic interface with standard semantics that can be interpreted by intermediaries almost as well as by the machines that originate services. The result is an application that allows for layers of transformation and indirection that are independent of the information origin, which is very useful for an Internet-scale, multi-organization, anarchically scalable information system. RPC mechanisms, in contrast, are defined in terms of language APIs, not network-based applications." For example, HTTP APIs are generally cacheable, RPC mechanisms generally are not.
"HEAD" and "OPTIONS" are the two obvious non-verb standard HTTP methods. :)
"Great minds think alike" 😃
Yes. That's a problem of OAI using a map for pathItems. I could have chosen to directly reference an array of pathItems in controls but then it wouldn't be 100% compatible with existing tools and libs (eg. swagger-ui) which is I think a strength ot the OHM format. Eg in the paging implementation, you can have 2 links with the same path+method (eg. "first page" and "previous page"). I worked around it by setting a fragment in the path to distinguish the 2 affordances. This fragment being ignored server-side. The problem of an enum list is that if you have several params, you don't know which combination of enum is allowed. And I don't see how to associate an affordance (eg. "first page") to an enum value.
I opened github.com/cbornet/ohm/issues/1 to track this issue.
If Roy says it, I guess this is it ... 😅 . But we still call procedures remotely...
I should get some sleep 🤦...