You can find the diff of the changes here [2] <https://github.com/hevayo/restful-apim/commit/ace429f3f4f2c62c36c5b4d55e9637c5db24b2ae>
[2] https://github.com/hevayo/restful-apim/commit/ace429f3f4f2c62c36c5b4d55e9637c5db24b2ae On Fri, Apr 3, 2015 at 12:56 PM, Joseph Fonseka <[email protected]> wrote: > Hi All > > Please find the latest API definition @ [1] > <http://hevayo.github.io/restful-apim/#/> with the following changes. > > 1. All the resources are updated with the relevant HTTP headers and > responses proposed by Frank. > 2. Added search condition grammar for API search. > 3. Added next page and previous page for "List" models > 4. Added operational resource for updating tier permissions sent by > Sanjeewa. > > Some more issues to discuss > 1. Currently API Id is made from a composite key > including (name/version/provider). In the REST API we thought of passing > the API ID as a concatenated string with the above 3 attributes delimited > by a special character ( thinking of + ). Is there a better approach to > handle this ? > > 2. Should we come up with application specific error codes to passed in > Error objects. Following are the benefits. > - Same HTTP error code can be mapped to two different errors (eg. in > /apis/{apiId}/document/{documentId} can return 404 if either api or > document missing ) > - If client wants to localize errors he can do with error codes. > > Please share your thoughts. > > Thanks > Jo > > [1] http://hevayo.github.io/restful-apim/#/ > > On Wed, Apr 1, 2015 at 6:35 PM, Sanjeewa Malalgoda <[email protected]> > wrote: > >> Hi Jo, >> Here i have attached updated apim.yaml file with my suggestions. >> Lets merge that to latest code. >> >> Thanks, >> sanjeewa. >> >> On Wed, Apr 1, 2015 at 1:55 PM, Sanjeewa Malalgoda <[email protected]> >> wrote: >> >>> Hi All, >>> >>> Here are my suggestions on this implementation. >>> When we design rest API for API Management functionality we need to >>> focus bit on publisher/ store aspects as well. Or we may need to have >>> control at some point based on the logged in user. >>> Here is one example: >>> >>> /apis >>> GET /apis >>> API provider should be mandatory field when it comes to publisher >>> context. >>> API consumer should be mandatory field when it comes to store context. >>> Or we should be able to retrieve current user by using JWT comes with >>> request or from access token. Still need to if request comes to store or >>> publisher context. >>> >>> And based on current user permissions we may need enable, disable API >>> add/modification via post, put, delete. >>> >>> Also for tiers we may have >>> >>> /tiers >>> >>> post >>> /tiers/{tierName}/update-permission >>> >>> Request body >>> { >>> "rolePermission": { >>> "access": "", >>> "roles": "" >>> } >>> } >>> >>> >>> Also for apis/{apiId} PUT need to have response with 409 Conflict as >>> well. Normally when we update resource with some information it cannot be >>> accessed due to some reason. So IMO having 409 as well would be helpful(in >>> addition to 412) >>> >>> It would be ideal /apis/{apiId}/change-lifecycle success response >>> returns 200 status code as we normally use 201 to indicate that new >>> resource created. >>> In this particular case we do update for existing resource state. >>> >>> We may include additional response code to /apis/{apiId}/documents GET >>> because we may have 2 situations. >>> 01. API does not exists(We can consider 412 for response code) >>> 02. API exists but documents not available(we can consider 404 as >>> requested resource is document). >>> >>> And same should apply to /apis/{apiId}/documents/{documentId} GET as >>> well. >>> >>> And we need to finalize about security model for this rest API. For that >>> we may consider few options. >>> >>> 01. Oath2 secured API. >>> 02. Basic auth secured rest API. >>> 03. Other security mechanisms. >>> >>> My personal opinion is this rest API should be independent from security >>> protocol. >>> And our rest API should not rely on any security related information >>> when in process request. >>> If we need to verify user is having permission to do some task then we >>> should not do it in rest API level(api subscriber should not allow to >>> update API). >>> >>> >>> Thanks, >>> sanjeewa. >>> >>> On Tue, Mar 31, 2015 at 11:07 PM, Joseph Fonseka <[email protected]> >>> wrote: >>> >>>> Hi Frank >>>> >>>> Yes 2pm is fine for me, my skype is "jpfonseka". Will ask "Sanjeewa >>>> Malalgoda" to join as well he was working on the ground work for the >>>> implementation. >>>> >>>> Thanks & Regards >>>> Jo >>>> >>>> >>>> >>>> On Tue, Mar 31, 2015 at 5:03 PM, Frank Leymann <[email protected]> wrote: >>>> >>>>> Hi Jo, >>>>> >>>>> is it possible for you to have a call tomorrow, Wednesday, 4/1, 2pm >>>>> Colombo time (i.e. 10:30am Germany, daylight-savings-time). I thing a >>>>> 30...60 minutes will be suffice. Main purpose would be how to proceed :-) >>>>> >>>>> I find Skype more reliable than Hangouts. Would you mind about a Skype >>>>> call? My SkypeID is frank.leymann >>>>> >>>>> Talk to you then! >>>>> >>>>> >>>>> Best regards, >>>>> Frank >>>>> >>>>> 2015-03-30 13:03 GMT+02:00 Joseph Fonseka <[email protected]>: >>>>> >>>>>> 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>* >>>>>> >>>>>> >>>>> >>>> >>>> >>>> -- >>>> >>>> -- >>>> *Joseph Fonseka* >>>> WSO2 Inc.; http://wso2.com >>>> lean.enterprise.middleware >>>> >>>> mobile: +94 772 512 430 >>>> skype: jpfonseka >>>> >>>> * <http://lk.linkedin.com/in/rumeshbandara>* >>>> >>>> >>> >>> >>> -- >>> >>> *Sanjeewa Malalgoda* >>> WSO2 Inc. >>> Mobile : +94713068779 >>> >>> <http://sanjeewamalalgoda.blogspot.com/>blog >>> :http://sanjeewamalalgoda.blogspot.com/ >>> <http://sanjeewamalalgoda.blogspot.com/> >>> >>> >>> >> >> >> -- >> >> *Sanjeewa Malalgoda* >> WSO2 Inc. >> Mobile : +94713068779 >> >> <http://sanjeewamalalgoda.blogspot.com/>blog >> :http://sanjeewamalalgoda.blogspot.com/ >> <http://sanjeewamalalgoda.blogspot.com/> >> >> >> > > > -- > > -- > *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
