[aerogear-dev] iOS API cookbook examples

Tue Mar 19 09:04:08 EDT 2013

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 at apache.org> wrote:

> On Tue, Mar 19, 2013 at 1:25 PM, Christos Vasilakis <cvasilak at gmail.com> wrote:
>> 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
> 
> 
> 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 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
>> 
>> 
>> _______________________________________________
>> 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