Hi, for the needs of [1] we created a page that collectively has code examples for all the different subsystems available in iOS. Much of the content used to reside in API.md [2], but now that we have moved it inside the API documentation, we though it would be better instead of removing the file completely, to convert it to a web page that will be hosted on our web site. I have converted to asciidoc and added some more content for the basic concept of the available iOS subsystems. The result can be found here [3] Wdyt? Thanks Christos [1] https://issues.jboss.org/browse/AEROGEAR-1007 [2] https://github.com/aerogear/aerogear-ios/blob/master/API.md [3] http://tinyurl.com/cnvb6e6 _______________________________________________ aerogear-dev mailing list aerogear-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/aerogear-dev

On Mar 18, 2013, at 10:33 AM, Daniel Bevenius <daniel.bevenius(a)gmail.com&gt; wrote: Nice work! Was wondering about this sentence: Paging metadata located in the server response (either in the headers, in the body or using [webLinking are used to identify the next or the previous result set. Could that perhaps be changed to something like (either in the headers by webLinking or custom headers, or in the body). I changed to your suggestion, it sounds better! I noticed a few character that are not being represented properly: A Pipeline object represents a ‘collection’ of server connections (aka Pipes). The class offers simple APIs to add, remove or get access to a ‘data store’ The class offers simple APIs to add, remove, or get access to a ‘authentication module’. fixed, (missed it cause the locally generated html didn't have these weird chars appended) /Dan Thanks for reviewing it! - Christos On 18 March 2013 09:11, Christos Vasilakis <cvasilak(a)gmail.com&gt; wrote: > > Hi, > > for the needs of [1] we created a page that collectively has code examples > for all the different subsystems available in iOS. Much of the content used > to reside in API.md [2], but now that we have moved it inside the API > documentation, we though it would be better instead of removing the file > completely, to convert it to a web page that will be hosted on our web site. > > I have converted to asciidoc and added some more content for the basic > concept of the available iOS subsystems. The result can be found here [3] > > Wdyt? > > Thanks > Christos > > [1] https://issues.jboss.org/browse/AEROGEAR-1007 > [2] https://github.com/aerogear/aerogear-ios/blob/master/API.md > [3] http://tinyurl.com/cnvb6e6 > > > > > _______________________________________________ > aerogear-dev mailing list > aerogear-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/aerogear-dev _______________________________________________ aerogear-dev mailing list aerogear-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/aerogear-dev _______________________________________________ aerogear-dev mailing list aerogear-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/aerogear-dev

Hi thanks for reviewing it answers inline On Mar 19, 2013, at 9:42 AM, Matthias Wessendorf <matzew(a)apache.org&gt; wrote: > Nice document! > > A few comments on the content of the cookbook ! > > > > * different iOS subsystems > -> not sure I like 'subsystem' part in the document I changed the description a bit removing the 'subsystem' part. > * "Pipe and Pipeline with Paging" > -> not sure, at this point, it's clear what Pipe/Pipeline is - and how > that could have to do with paging > Not sure... but I'd use "HTTP REST abstraction + Pagination" > I removed 'with Paging' part and replaced it with plus, so that not be confused paging with the Pipeline concept. Since we do some introductory description on the concepts (Pipe, Pipeline, Data Manager, Auth.) I think we can stick to these name

> * "The save method is also responsible for updating an object. However > this happens only when there is an id property/field available:" > -> the "id" is wrong; it should say recordId (since it's > configurable), adding a link to that property would be nice > ----> similar for the remove case > I created a NOTE describing the 'id' - recordId relationship and link to it from the respective methods. I think it's better now

> * Read all data from the server > --> let's move that to the top - before the save ok

> --> reading a specific entry (with a given id/recordID) would be a > nice example too ok > > * Since we are pointing to a RESTful endpoint, the API issues a HTTP > GET request. The JSON output of the above NSLog() call looks like > this: > ==> Do you htink it makes sense to give the trace for the > NSDictionary? IMO we can just get rid of it - since JSON is only the > output if the backend generates JSON… > ok i got rid of it. > > * Paging header -> I'd use 'Pagination' > > * (either in the headers by webLinking or custom headers, > -> either in the headers via WebLinking RFC or custom headers, ok > > > * For example, in Twitter case, paging metadata are located in the > body of the response, using next_page or previous_page to identify the > next or previous result set respectively. > ---> For example, Twitter's paging metadata is located in the body of > the response. > > ==> Just link to their API - no need to explain their (current) > pagination API :) > https://dev.twitter.com/docs/api/1/get/search > NOTE: Their 1.1 API version is DIFFERENT… > ok

> > > * === Move Forward in the result set || === Move Backward in the result set > ----> Can you make this not code - just the actual paging should be code?! > > ok > > > * Persistent Storage system > ==> Not sure the "OTP" example fits the context - there is nothing > mentioned on OTP here - perhaps some more detailed example here > (referencing the OTP lib) would be a bit more helpful > ok, I added a small description for OTP so it's more relevant. > > > Again, nice work! Thanks for reviewing!

- Christos > > On Mon, Mar 18, 2013 at 10:03 AM, Christos Vasilakis <cvasilak(a)gmail.com&gt; wrote: >> On Mar 18, 2013, at 10:33 AM, Daniel Bevenius <daniel.bevenius(a)gmail.com&gt; >> wrote: >> >> Nice work! >> >> Was wondering about this sentence: >> Paging metadata located in the server response (either in the headers, in >> the body or using [webLinking are used to identify the next or the previous >> result set. >> Could that perhaps be changed to something like (either in the headers by >> webLinking or custom headers, or in the body). >> >> >> I changed to your suggestion, it sounds better! >> >> >> I noticed a few character that are not being represented properly: >> A Pipeline object represents a ‘collection’ of server connections (aka >> Pipes). >> The class offers simple APIs to add, remove or get access to a ‘data >> store’ >> The class offers simple APIs to add, remove, or get access to a >> ‘authentication module’. >> >> >> fixed, (missed it cause the locally generated html didn't have these weird >> chars appended) >> >> >> /Dan >> >> >> Thanks for reviewing it! >> >> - >> Christos >> >> >> >> >> On 18 March 2013 09:11, Christos Vasilakis <cvasilak(a)gmail.com&gt; wrote: >>> >>> Hi, >>> >>> for the needs of [1] we created a page that collectively has code examples >>> for all the different subsystems available in iOS. Much of the content used >>> to reside in API.md [2], but now that we have moved it inside the API >>> documentation, we though it would be better instead of removing the file >>> completely, to convert it to a web page that will be hosted on our web site. >>> >>> I have converted to asciidoc and added some more content for the basic >>> concept of the available iOS subsystems. The result can be found here [3] >>> >>> Wdyt? >>> >>> Thanks >>> Christos >>> >>> [1] https://issues.jboss.org/browse/AEROGEAR-1007 >>> [2] https://github.com/aerogear/aerogear-ios/blob/master/API.md >>> [3] http://tinyurl.com/cnvb6e6 >>> >>> >>> >>> >>> _______________________________________________ >>> aerogear-dev mailing list >>> aerogear-dev(a)lists.jboss.org >>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >> >> >> _______________________________________________ >> aerogear-dev mailing list >> aerogear-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/aerogear-dev >> >> >> >> _______________________________________________ >> aerogear-dev mailing list >> aerogear-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/aerogear-dev > > > > -- > Matthias Wessendorf > > blog: http://matthiaswessendorf.wordpress.com/ > sessions: http://www.slideshare.net/mwessendorf > twitter: http://twitter.com/mwessendorf > > _______________________________________________ > aerogear-dev mailing list > aerogear-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/aerogear-dev _______________________________________________ aerogear-dev mailing list aerogear-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/aerogear-dev

Hi I have updated the doc with the comments thanks for reviewing it! - Christos On Mar 19, 2013, at 2:36 PM, Matthias Wessendorf <matzew(a)apache.org&gt; wrote: > On Tue, Mar 19, 2013 at 1:25 PM, Christos Vasilakis <cvasilak(a)gmail.com&gt; wrote: >> Hi >> >> thanks for reviewing it >> >> answers inline >> >> On Mar 19, 2013, at 9:42 AM, Matthias Wessendorf <matzew(a)apache.org&gt; wrote: >> >>> Nice document! >>> >>> A few comments on the content of the cookbook ! >>> >>> >>> >>> * different iOS subsystems >>> -> not sure I like 'subsystem' part in the document >> >> I changed the description a bit removing the 'subsystem' part. >> >> >>> * "Pipe and Pipeline with Paging" >>> -> not sure, at this point, it's clear what Pipe/Pipeline is - and how >>> that could have to do with paging >>> Not sure... but I'd use "HTTP REST abstraction + Pagination" >>> >> >> I removed 'with Paging' part and replaced it with plus, so that not be confused paging with the Pipeline concept. >> Since we do some introductory description on the concepts (Pipe, Pipeline, Data Manager, Auth.) I think we can stick to these name > > > Datamanager + Auth has a more generic meaning - What's wrong with > using ""HTTP REST abstraction + Pagination"" as the header? > After that header we do (and should) use the Pipe/Pipeline.. > > > > >> >>> * "The save method is also responsible for updating an object. However >>> this happens only when there is an id property/field available:" >>> -> the "id" is wrong; it should say recordId (since it's >>> configurable), adding a link to that property would be nice >>> ----> similar for the remove case >>> >> >> I created a NOTE describing the 'id' - recordId relationship and link to it from the respective methods. I think it's better now > > I think that "Before performing save, ensure that the object you are > trying to save, has the id property set." is actually a bit wrong, > since the property on the API is actually called recordId...... Would > be better to stick with those names (similar on remove) > > > > >> >> >>> * Read all data from the server >>> --> let's move that to the top - before the save >> ok > > > Can you move the "Read a specific object" to the top? > -Read a specific object > -Read all > -save > etc > > :-) > > > >> >>> --> reading a specific entry (with a given id/recordID) would be a >>> nice example too >> ok >> >>> >>> * Since we are pointing to a RESTful endpoint, the API issues a HTTP >>> GET request. The JSON output of the above NSLog() call looks like >>> this: >>> ==> Do you htink it makes sense to give the trace for the >>> NSDictionary? IMO we can just get rid of it - since JSON is only the >>> output if the backend generates JSON… >>> >> >> ok i got rid of it. >> >>> >>> * Paging header -> I'd use 'Pagination' >>> >>> * (either in the headers by webLinking or custom headers, >>> -> either in the headers via WebLinking RFC or custom headers, >> ok >> >>> >>> >>> * For example, in Twitter case, paging metadata are located in the >>> body of the response, using next_page or previous_page to identify the >>> next or previous result set respectively. >>> ---> For example, Twitter's paging metadata is located in the body of >>> the response. >>> >>> ==> Just link to their API - no need to explain their (current) >>> pagination API :) >>> https://dev.twitter.com/docs/api/1/get/search >>> NOTE: Their 1.1 API version is DIFFERENT… >>> >> ok > > > For example, the Twitter search paging metadata is located in the body > of the response; > > >> >>> >>> >>> * === Move Forward in the result set || === Move Backward in the result set >>> ----> Can you make this not code - just the actual paging should be code?! >>> >>> >> >> ok >>> >>> >>> * Persistent Storage system >>> ==> Not sure the "OTP" example fits the context - there is nothing >>> mentioned on OTP here - perhaps some more detailed example here >>> (referencing the OTP lib) would be a bit more helpful >>> >> >> ok, I added a small description for OTP so it's more relevant. >>> >> >>> >>> Again, nice work! >> >> Thanks for reviewing! > > > Thanks for taking care - Oh... :) one more question: should we add a > sentence (at the begining) Click here for the full API doc ? > > -Matthias > > > >> >> - >> Christos >> >>> >>> On Mon, Mar 18, 2013 at 10:03 AM, Christos Vasilakis <cvasilak(a)gmail.com&gt; wrote: >>>> On Mar 18, 2013, at 10:33 AM, Daniel Bevenius <daniel.bevenius(a)gmail.com&gt; >>>> wrote: >>>> >>>> Nice work! >>>> >>>> Was wondering about this sentence: >>>> Paging metadata located in the server response (either in the headers, in >>>> the body or using [webLinking are used to identify the next or the previous >>>> result set. >>>> Could that perhaps be changed to something like (either in the headers by >>>> webLinking or custom headers, or in the body). >>>> >>>> >>>> I changed to your suggestion, it sounds better! >>>> >>>> >>>> I noticed a few character that are not being represented properly: >>>> A Pipeline object represents a ‘collection’ of server connections (aka >>>> Pipes). >>>> The class offers simple APIs to add, remove or get access to a ‘data >>>> store’ >>>> The class offers simple APIs to add, remove, or get access to a >>>> ‘authentication module’. >>>> >>>> >>>> fixed, (missed it cause the locally generated html didn't have these weird >>>> chars appended) >>>> >>>> >>>> /Dan >>>> >>>> >>>> Thanks for reviewing it! >>>> >>>> - >>>> Christos >>>> >>>> >>>> >>>> >>>> On 18 March 2013 09:11, Christos Vasilakis <cvasilak(a)gmail.com&gt; wrote: >>>>> >>>>> Hi, >>>>> >>>>> for the needs of [1] we created a page that collectively has code examples >>>>> for all the different subsystems available in iOS. Much of the content used >>>>> to reside in API.md [2], but now that we have moved it inside the API >>>>> documentation, we though it would be better instead of removing the file >>>>> completely, to convert it to a web page that will be hosted on our web site. >>>>> >>>>> I have converted to asciidoc and added some more content for the basic >>>>> concept of the available iOS subsystems. The result can be found here [3] >>>>> >>>>> Wdyt? >>>>> >>>>> Thanks >>>>> Christos >>>>> >>>>> [1] https://issues.jboss.org/browse/AEROGEAR-1007 >>>>> [2] https://github.com/aerogear/aerogear-ios/blob/master/API.md >>>>> [3] http://tinyurl.com/cnvb6e6 >>>>> >>>>> >>>>> >>>>> >>>>> _______________________________________________ >>>>> aerogear-dev mailing list >>>>> aerogear-dev(a)lists.jboss.org >>>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >>>> >>>> >>>> _______________________________________________ >>>> aerogear-dev mailing list >>>> aerogear-dev(a)lists.jboss.org >>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >>>> >>>> >>>> >>>> _______________________________________________ >>>> aerogear-dev mailing list >>>> aerogear-dev(a)lists.jboss.org >>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >>> >>> >>> >>> -- >>> Matthias Wessendorf >>> >>> blog: http://matthiaswessendorf.wordpress.com/ >>> sessions: http://www.slideshare.net/mwessendorf >>> twitter: http://twitter.com/mwessendorf >>> >>> _______________________________________________ >>> aerogear-dev mailing list >>> aerogear-dev(a)lists.jboss.org >>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >> >> >> _______________________________________________ >> aerogear-dev mailing list >> aerogear-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/aerogear-dev > > > > -- > Matthias Wessendorf > > blog: http://matthiaswessendorf.wordpress.com/ > sessions: http://www.slideshare.net/mwessendorf > twitter: http://twitter.com/mwessendorf > > _______________________________________________ > aerogear-dev mailing list > aerogear-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/aerogear-dev _______________________________________________ aerogear-dev mailing list aerogear-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/aerogear-dev