Cool.. thanks Frank.
On Wed, Apr 1, 2015 at 4:58 PM, Frank Leymann <[email protected]> wrote:
> Hi Nirmal,
>
> camel case should not be used because:
>
> - the domain name (aka host) is not case sensitive by definition,
> - some servers treat the path not as case sensitive
>
> thus, camel case style will be confusing, implying differences in API
> names that don't exist. Nevertheless, a couple of vendors use camel style,
> but the public critique is that these APIs are designed by Java programmers
> ;-)
>
> Using underscores is typically seen as problematic, because API URLs are
> often rendered in HTML pages (e.g. in documentation; as error descriptions;
> in generated pages;...). And the browser will interpret them as links,
> thus, rendering them as underlined: the underscore is then hard to read.
>
> As a *consequence*, the general recommendation is to *use hyphens* ("-").
> :-)
>
>
>
> Best regards,
> Frank
>
> 2015-04-01 10:34 GMT+02:00 Nirmal Fernando <[email protected]>:
>
>> 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/
>>
>>
>>
>
--
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
