3 ms·

I'm not sure what the common idioms for Javascript/node.js API design are, but I think this API is really ugly. prodAdv = aws.createProdAdvClient(yourAccessK

by jfarmer 15y ago

I'm not sure what the common idioms for Javascript/node.js API design are, but I think this API is really ugly. prodAdv = aws.createProdAdvClient(yourAccessKeyId, yourSecretAccessKey, yourAssociateTag); prodAdv.call("ItemSearch", {SearchIndex: "Books", Keywords: "Javascript"}, function(result) { console.log(JSON.stringify(result)); }) createProdAdvClient? Accessing the .call method directly? Edit: Also, didn't notice, but the upper-case key names in the hash passed to the call method are also ugly, IMO.

jonknee 15y ago
The upper-case key names are from Amazon... http://docs.amazonwebservices.com/AWSECommerceService/2011-08-01/DG/ItemSearch.html http://docs.amazonwebservices.com/AWSECommerceService/2011-0... As for the method name, what would you have chosen? It's a generic official name "Product Advertising API", not a lot of room there. I guess leaving off the create wouldn't heart, productAdvertisingClient() is pretty verbose, but productAdvClient() not so bad.
- jfarmer 15y ago
  I would rather have something verbose that corresponds to the underlying API than something I have to guess or remember. Is it createProdAdvClient, createProductAdvClient, createProdAdvertisingClient, createProdAdvertClient, etc.? Completely arbitrary. My ideal API clients have a base layer that maps intuitively to the underlying API, and a developer-friendly upper layer with idiomatic method calls. A common trick in Ruby, for example, is to give the API client a proxy method (e.g., api) that uses method_missing to map method calls to API end points. You wind up with API clients that look like client.api.some_method(...). Under the hood it might transform some_method into "someMethod" before it makes the API call. However, if you want, you can still access the raw API endpoints programmatically. Just my preference, I realize, but I think it's important for libraries to idiomatic.

by jfarmer 15y ago

jonknee 15y ago

The upper-case key names are from Amazon... http://docs.amazonwebservices.com/AWSECommerceService/2011-08-01/DG/ItemSearch.html http://docs.amazonwebservices.com/AWSECommerceService/2011-0... As for the method name, what would you have chosen? It's a generic official name "Product Advertising API", not a lot of room there. I guess leaving off the create wouldn't heart, productAdvertisingClient() is pretty verbose, but productAdvClient() not so bad.

jfarmer 15y ago
I would rather have something verbose that corresponds to the underlying API than something I have to guess or remember. Is it createProdAdvClient, createProductAdvClient, createProdAdvertisingClient, createProdAdvertClient, etc.? Completely arbitrary. My ideal API clients have a base layer that maps intuitively to the underlying API, and a developer-friendly upper layer with idiomatic method calls. A common trick in Ruby, for example, is to give the API client a proxy method (e.g., api) that uses method_missing to map method calls to API end points. You wind up with API clients that look like client.api.some_method(...). Under the hood it might transform some_method into "someMethod" before it makes the API call. However, if you want, you can still access the raw API endpoints programmatically. Just my preference, I realize, but I think it's important for libraries to idiomatic.