

Ask HN: Designing an SDK - shobyabdi

First time asking HN anything. I've been tasked with designing an SDK for an App Store, the problem is I have never designed an SDK. Can anyone point me to any resources that can guide me or best practices anyone in HN can recommend?<p>Technology unknown, just need an idea of best practices and possible resources I can look to.<p>Thx HN
======
hga
Do you have an API to start with, or is that also part of your task?

------
mahmud
The heart of an SDK is blueprint template, think of a class definition, and
various programming languages, toolchains and platforms have _instances_ of
that blueprint. So you need to design the parts they all have in common, and
leave the platform specific parts to the lower bootstrapping layers; build
utilities, configuration files, even host introspection (if you can ask
uname(1), don't ask the user.)

If the SDK is for a web API or an RPC style service, then you start by
designing the data-interchange format. If you have a few messages to pass
around, you can create the specifications for those messages, leaving enough
room for exception handling, security, logging and auditing, and most
importantly versioning. E.g.

    
    
       message {
          bool: error?
          error: error-value
          struct: {
             int: count
             values
          } result
          float: api-version
          struct: log-info
       }
    

This is the prototypical message in RPC style APIs when there are few, less
than 20 different messages. And this is very XML-RPC API you will ever come
across.

Another approach is to structure the RPC API around a query language of some
sort.

If you have many CRUD and reporting operations that act on different data
types, you can roll out a SQL, or even a hash-table like set of operations
over RPC/Web Services. For example, instead of having: ListEmployees
GetEmployee GetNewEmployee GetUnpaidEmployees

ad infinitum

You can have a "select" operation, with various arguments, and take care of
the query parsing on the server side.

    
    
        Get(Type, Where &optional GroupBy, Having, OrderBy)
    

then to get unpaid employees (where everything after &optional is optional)

    
    
        Get("Employee", "payment_date <=" . Date(..), "employee_id")
       

Or something similar.

This takes a bit more work on the server side, but it's doable in a week by a
good hacker. Look at the Zuora SOAP API for an example of this.

If you want to see a "NoSQL" flavor, take a look at SugarCRM's SOAP API. It's
entirely getter/setter based and very clean.

What matters is that you treat the server side query processing as a mini
compiler project, which is what it is, so don't hesitate to pull out the
formal theory to make sure nothing unexpected slips past. If you cheat and
whish away the complexity by coding for a best-case scenario, you lose.

\-----

Those were data-oriented remote message services. There are many many more
styles and flavors, and as the only API junkie that I know of (I practically
make my living integrating software) I feel I should do other styles a little
justice and do a separate writeup.

