[aerogear-dev] iOS API cookbook examples

[Christos Vasilakis]

Hi

thanks for reviewing it

answers inline

On Mar 19, 2013, at 9:42 AM, Matthias Wessendorf <matzew at apache.org> 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 at gmail.com> wrote:
>> On Mar 18, 2013, at 10:33 AM, Daniel Bevenius <daniel.bevenius at gmail.com>
>> 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 at gmail.com> 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 at lists.jboss.org
>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>> 
>> 
>> _______________________________________________
>> aerogear-dev mailing list
>> aerogear-dev at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>> 
>> 
>> 
>> _______________________________________________
>> aerogear-dev mailing list
>> aerogear-dev at 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 at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/aerogear-dev