This is very helpful Frank, and as you mentioned these controlled-resources are always lead to discussion. Do you have any comments on the usage of '-' instead of camel case ?
On Tue, Mar 31, 2015 at 10:51 PM, Frank Leymann <[email protected]> wrote: > Hi Jo, hi Manu, > > how to cope with "actions" that cannot be mapped onto the CRUD methods on > individual resources or collection resources is always a matter of > discussion and taste when designing REST interfaces. > > A very often used guideline is to use so-called *controller resources*. I > controller resources represents an application specific operation that acts > on one or more individual resources or collection resources in an atomic > manner. The copy-api is such a controller resource. > > There are two ways to design URIs of controller resources. First, you > append the name of the "action" to one of the URIs that you atomically want > to act on, and other parameters follow in the query string; sometimes it is > random which of the URIs to append the name of the action to - this is why > I personally don't like this naming scheme. The second design uses the name > of the "action" as URI and the query string contains the parameters > required by the "action" - this is what I personally prefer because it's > deterministic and symmetric (but again, it's a matter of taste. However > you design the URI you use POST as the http method to interact with the > controller resource. > > In our concrete case of copy-api the two options are: > > 1. /apis/{apiId}/copy-api > or > 2. /copy-api?{apiID} > > By the way, the similar case is the change-lifecycle controller resource. > > Another reason why I like API design (2) is as follows. Often you need > actions on individual resources that don't manipulate (or retrieve) a > resource. Such actions are designed as resources called *processing > function resources* or *computing resources*. The standard example is > verifying a credit card. The design of the URIs of such processing function > resources always follows number (2). Because processing functions > resources never manipulate resources its http method is always GET, by the > way. > > Finally, controller resources are used from time to time to update parts > of individual resources. Http has the PATCH method for this purpose, but > not all web servers support PATCH. PUT itself will substitute complete > resources, i.e. updating parts of an individual resource is not intended > via PUT. This is why specific controller resources may be used for partial > updates. > > > > > Best regards, > Frank > > 2015-03-30 19:57 GMT+02:00 Joseph Fonseka <[email protected]>: > >> Hi Manu >> >> Copy API will duplicate not just the resource it will duplicate all the >> resources associated to it as well eg. Documents. So re-posting the API >> resource json will not be sufficient in this particular case. But there is >> a possibility of duplicating the associated resources from the client as >> well but IMHO that will complicated the client implementation. >> >> Nevertheless its a problem that we face how to represent an action as a >> resource. Currently we have adopted "<action>-<resource or attr acted >> upon>" kind of notation. >> >> Regards >> Jo >> >> >> On Mon, Mar 30, 2015 at 4:49 PM, Manuranga Perera <[email protected]> wrote: >> >>> Hi Frank, >>> I see few endpoints representing actions rather than resources. For >>> example POST /apis/{apiId}/copy-api. >>> This is an action because there is no resource called copy-api. I would >>> rather see it as posting an existing API to the /apis. >>> In a HATEOS system we will be posting the href of an existing API to >>> /apis endpoint. Since we are not there yet, we can use some json >>> representation of the existing API. >>> >>> What do you think? >>> >>> On Tue, Mar 31, 2015 at 12:03 AM, Joseph Fonseka <[email protected]> >>> wrote: >>> >>>> Hi Frank >>>> >>>> Thanks for the feedback. And it is nice to see how we can control >>>> cashing and concurrency with the additional headers. We will update the >>>> remaining APIs with the same concepts. >>>> >>>> Please let us know a convenient time for a call to discuss on it >>>> further. >>>> >>>> Also we will try to document these design decisions and concepts to >>>> benefit APIs created in the future. >>>> >>>> BTW. The changes were pushed to the repo. >>>> >>>> Thanks >>>> Jo >>>> >>>> >>>> [1] http://hevayo.github.io/restful-apim/ >>>> >>>> On Sat, Mar 28, 2015 at 12:47 AM, Frank Leymann <[email protected]> wrote: >>>> >>>>> Hi Jo, >>>>> >>>>> again, thanks for your work: we'll get a nice RESTful API :-) In the >>>>> Richardson maturity model we'll get to level 2 (not level 3 because we are >>>>> leaving out HATEOS - which is something that is not used often today in >>>>> practice anyhow). >>>>> >>>>> I exported the YAML of the API, put it into a Word document and used >>>>> the "change tracking" feature to comment/modify across the document - >>>>> please find the document attached. (Frank Input - API Manager API - >>>>> 2015-03-27.docx) >>>>> >>>>> All the changes I made to YAML itself is in the separate swagger YAML >>>>> file I attached too. I used the swagger 2.0 tool to create this YAML, and >>>>> the tool shows no syntax errors... So you may import it into your tool >>>>> without problems. (FL Input API Manager API - 2015-03-27.yaml) >>>>> >>>>> I worked on the apis of the /apis and /apis/{apiID} resources. Before >>>>> I continue, I suggest that we have a discussion (i.e. a call) to discuss >>>>> the changes/suggestions I made. We need to agree whether this fits into >>>>> the >>>>> plan for implementing in the next release. >>>>> >>>>> Looking forward.... >>>>> >>>>> >>>>> >>>>> Best regards, >>>>> Frank >>>>> >>>>> 2015-03-26 4:52 GMT+01:00 Joseph Fonseka <[email protected]>: >>>>> >>>>>> Hi Frank >>>>>> >>>>>> What are the headers we should include ? >>>>>> >>>>>> 1. For the access token header we can define it globally in the >>>>>> security definition [1] >>>>>> <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#securityDefinitionsObject> >>>>>> 2. Content-type headers are covered by the consumes and produces >>>>>> attributes [2] >>>>>> <https://github.com/hevayo/restful-apim/blob/master/apim.yaml#L18-L19> >>>>>> 3. For post methods we have an option of sending "Link" header with a >>>>>> URL to newly created resource rather than returning newly created >>>>>> resource >>>>>> JSON. >>>>>> >>>>>> Thanks >>>>>> Jo >>>>>> >>>>>> [1] >>>>>> https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#securityDefinitionsObject >>>>>> >>>>>> [2] >>>>>> https://github.com/hevayo/restful-apim/blob/master/apim.yaml#L18-L19 >>>>>> >>>>>> On Wed, Mar 25, 2015 at 3:51 PM, Frank Leymann <[email protected]> >>>>>> wrote: >>>>>> >>>>>>> Hi Jo, >>>>>>> >>>>>>> nice piece of work! >>>>>>> >>>>>>> What is still needed is a description of the header fields for both, >>>>>>> the requests and APIs. >>>>>>> >>>>>>> >>>>>>> >>>>>>> Best regards, >>>>>>> Frank >>>>>>> >>>>>>> 2015-03-24 17:34 GMT+01:00 Joseph Fonseka <[email protected]>: >>>>>>> >>>>>>>> Hi All >>>>>>>> >>>>>>>> We are planing to implement a RESTFul API to expose the API Manager >>>>>>>> functionality. This will be a replacement to the currently provided >>>>>>>> Store >>>>>>>> and Publisher APIs [1] >>>>>>>> <https://docs.wso2.com/display/AM180/Publisher+APIs> & [2] >>>>>>>> <https://docs.wso2.com/display/AM180/Store+APIs>. >>>>>>>> >>>>>>>> Main Motivation. >>>>>>>> 1. The current APIs are not RESTful and they do not cover all the >>>>>>>> functionality. >>>>>>>> 2. To make it easy to integrate and automate API manager >>>>>>>> functionality with 3rd party systems. >>>>>>>> 3. To provide better security with Oauth. >>>>>>>> 4. To provide better versioning and documentation with the API. >>>>>>>> >>>>>>>> As a start we have written a draft version of the API definition >>>>>>>> which you can find here [3] <http://hevayo.github.io/restful-apim/> >>>>>>>> . >>>>>>>> >>>>>>>> Following is a rough implementation plan. >>>>>>>> 1. Work on the API Definition, get feed back from users and >>>>>>>> finalize. >>>>>>>> 2. Implementation. ( Architecture , Jax-RS ?) >>>>>>>> 3. Adding Security. ( O-auth, scopes ? ) >>>>>>>> 4. Testing. >>>>>>>> 5. Documentation. >>>>>>>> >>>>>>>> API definition was written with Swagger 2 once completed we can use >>>>>>>> it to generate server stubs, client stubs and documentation. >>>>>>>> >>>>>>>> Please share your thoughts. >>>>>>>> >>>>>>>> Thanks >>>>>>>> Jo >>>>>>>> >>>>>>>> [1] https://docs.wso2.com/display/AM180/Publisher+APIs >>>>>>>> [2] https://docs.wso2.com/display/AM180/Store+APIs >>>>>>>> [3] http://hevayo.github.io/restful-apim/ >>>>>>>> >>>>>>>> -- >>>>>>>> *Joseph Fonseka* >>>>>>>> WSO2 Inc.; http://wso2.com >>>>>>>> lean.enterprise.middleware >>>>>>>> >>>>>>>> mobile: +94 772 512 430 >>>>>>>> skype: jpfonseka >>>>>>>> >>>>>>>> * <http://lk.linkedin.com/in/rumeshbandara>* >>>>>>>> >>>>>>>> >>>>>>> >>>>>> >>>>>> >>>>>> -- >>>>>> >>>>>> -- >>>>>> *Joseph Fonseka* >>>>>> WSO2 Inc.; http://wso2.com >>>>>> lean.enterprise.middleware >>>>>> >>>>>> mobile: +94 772 512 430 >>>>>> skype: jpfonseka >>>>>> >>>>>> * <http://lk.linkedin.com/in/rumeshbandara>* >>>>>> >>>>>> >>>>> >>>> >>>> >>>> -- >>>> >>>> -- >>>> *Joseph Fonseka* >>>> WSO2 Inc.; http://wso2.com >>>> lean.enterprise.middleware >>>> >>>> mobile: +94 772 512 430 >>>> skype: jpfonseka >>>> >>>> * <http://lk.linkedin.com/in/rumeshbandara>* >>>> >>>> >>>> _______________________________________________ >>>> Architecture mailing list >>>> [email protected] >>>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture >>>> >>>> >>> >>> >>> -- >>> With regards, >>> *Manu*ranga Perera. >>> >>> phone : 071 7 70 20 50 >>> mail : [email protected] >>> >>> _______________________________________________ >>> Architecture mailing list >>> [email protected] >>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture >>> >>> >> >> >> -- >> >> -- >> *Joseph Fonseka* >> WSO2 Inc.; http://wso2.com >> lean.enterprise.middleware >> >> mobile: +94 772 512 430 >> skype: jpfonseka >> >> * <http://lk.linkedin.com/in/rumeshbandara>* >> >> >> _______________________________________________ >> Architecture mailing list >> [email protected] >> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture >> >> > > _______________________________________________ > Architecture mailing list > [email protected] > https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture > > -- Thanks & regards, Nirmal Senior Software Engineer- Platform Technologies Team, WSO2 Inc. Mobile: +94715779733 Blog: http://nirmalfdo.blogspot.com/
_______________________________________________ Architecture mailing list [email protected] https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
