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
