[aerogear-dev] iOS API cookbook examples

[Matthias Wessendorf]

Nice document!

A few comments on the content of the cookbook !



* different iOS subsystems
-> not sure I like 'subsystem' part in the document

* "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"

* "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

* Read all data from the server
--> let's move that to the top - before the save
--> reading a specific entry (with a given id/recordID) would be a
nice example too

* 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...


* 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,


* 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...



* === 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?!




* 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




Again, nice work!

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