Question

I’m currently preparing to design a C or C++ library for accessing an existing Rest service, but here’s what I’m not sure about:

Most API Client libraries like this that I’ve seen simply provide a calling style that’s very close to the ReST API, where you have to read the ReST API docs to use it. They aren’t really written in they native style of the language, IMO. They are basically wrapping an http library, maybe an XML/JSON library and handling a few special things like auth:

STYLE 1:

paramList.add( "name", "Joe" )
response = makeARestCall( POST, "path/to/resource", paramList, miscAuthData );
if( result.code == 200 ) {
    //success
    xml = response.getXml();
    somethingWeCareAbout = xpath.parse( xml, "response/something/we/care/about" );
    print somethingWeCareAbout
} else {
    print "Something went wrong"
}

It seems much more natural to me to use the conventions of the language, rather than the API. Thinking of using the API as calling functions rather than accessing resources.

STYLE 2:

try {
   Api.setName( UserId, "Joe" );
   print Api.getSomethingWeCareAbout();
} catch( ApiException e ) {
   print e.getMessage();
}

I’ve written API Libraries in the latter style and they take much more work, but I find them much more natural to use and integrate into apps, especially for complex ReST APIs, but I’m not super experienced at this.

Is one style clearly better than the other? Is there a reason, other than ease of development, most seem to be written in the first style?

This library will definitely be used in multithreaded apps, and UIs, so please answer with threading in mind.

Answer 1

After thinking this over, a partial answer to my own question is that the first style is probably easier to multithread. Someone using the library can create a function like this:

void asyncRestCall( Method method, String resource, map<String,String> parameters, misc misc, function onCompletion ) {
    //fork a new thread
    ...

    //do the call
    result = makeARestCall( method, resource, parameters misc );

    //back in original thread
    ...

    onCompletion( result );
}

Whereas doing that once for every function call in style 2 is way more work.