Comments on: Implicit vs. explicit APIs

By: cakebaker

cakebaker — Sat, 03 May 2008 07:21:57 +0000

@all: Thanks for your comments!

@James: Yes, reading the source is a good way to learn what the code does. On the other hand it is a bad smell, if you have to read the code before you can use it… But as you said, this situation will hopefully become better with more documentation.

@Abhimanyu: Yes, that’s how the new find method looks like, at least in principle. In practice, the method signature is still the old one (for compatibility reasons):

find($conditions = null, $fields = array(), $order = null, $recursive = null)

@AndyB: Yes, the $options array has to be well documented, or else you have to dig into the code to figure out how it must look like.

@Anonymous: Hm, as far as I know, PHP doesn’t support keyword arguments, so you have to use an associative array to (partially) simulate keyword arguments.

By: Abi

Abi — Sat, 03 May 2008 01:04:51 +0000

Thanks for the excellent overview of the two types of APIs. As a programmer, I seem to prefer an implicit API because it feels much more elegant. However, when I first started using cakephp, I found the implicit find() pretty irritating and troublesome to get started. So, as a user, I prefer an explicit API. Ironic…

By: Anonymous

Anonymous — Fri, 02 May 2008 00:32:03 +0000

just skip this array abuse nonsense and get keyword arguments in python/django

By: AndyB

AndyB — Thu, 01 May 2008 16:36:30 +0000

IMHO Implicit API’s are only practicable, if the $options-array is well documented or even better: an object like in Java. If you can’t reuse your $options-array for several formerly explicit API’s, there is neither less documentation to write nor less code.
For the examples you brought up, it makes sense to use implicit API’s, but again: $options has to be well documented!

By: Abhimanyu

Abhimanyu — Thu, 01 May 2008 13:40:17 +0000

Hey, is this the new syntax ?
Model::find($type, $options = array()) // new syntax

By: leveille

leveille — Thu, 01 May 2008 13:13:19 +0000

Excellent breakdown of the differences between the two. I find myself favoring an explicit API, however that is likely because I spend most a lot my time creating/exposing web services. Though I suppose a RESTful resource request which allows the inclusion of actions would be considered implicit:

GET /articles;recent (implicit)
GET /articles;popular (implicit)
GET /articles;archived (implicit)
vs.
GET /articles (explicit)

By: James

James — Thu, 01 May 2008 11:16:57 +0000

Hi, I’ve just started using 1.2 and I had to hunt down the find() method in the API and look at the code to see what other functionality it has.

It makes sense to use just the one method and once the documentation is more extensive it will make it easier for people to see how and why the method behaves the way it does.