android - Design of an API SDK -

i'm posting here open question because i'm wondering best way design api sdk android.

here point.

we have apis (json/restful) exposed, but, want build sdk developers, wouldn't want implement calls themselves.

so see 3 ways consume api.

• synchronous way
• asynchronous way (2 sub parts in fact)
  • callback way
  • future way

as don't want force dev use or way do. wondering do.

multiple options here.

• implement the unit way.
  • a method returns final object , not care threading.
  • a method takes callback in parameter , trigger onresult() final object argument (it cares threading in background)
  • a method returns future, dev can decide when wants it.
• implement as single object.
  • the method returns object work on callback mode or future mode.
• just callbacks
• just futures
• whatever else

so, we're not sure as developers, guys prefer. , if ever faced problem, final decision?

thanks or feedback!

just map retrofit : http://square.github.io/retrofit/

this way can expose , easly many way use wrapper. in general try design simplest syntax , offer convenience interface possible.

good practice : write readme first, if it's easy understand, implement it.