[aerogear-dev] iOS API cookbook examples

Tue Mar 19 08:36:43 EDT 2013

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