[aerogear-dev] iOS API cookbook examples

Tue Mar 19 09:05:38 EDT 2013

<3 <3 <3

PERFECT !

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