CiviCRM Community Forums (archive)

The REST API interface makes some assumptions about the function naming convention that just don't hold up. But it would be great if they did! I'm writing some REST API client modules in other languages (mainly Ruby and Perl right now), and it's much easier to generate the URL from an autoloader-type method so you can do things like (examples in Perl):
$civicrm->contact_get($params);
or
$civicrm->activity_create($params);
without having to actually write each of those methods in the client. This keeps the client smaller, simpler, easier to maintain, and much more future-proof since you don't have to explicitly add every API function to the client libraries.

When I auto-generate a URL from the above Perl method call examples, I get rest.php?q=civicrm/contact/get&... and rest.php?q=civicrm/activity/create&... which both work fine. But stay tuned...

The REST interface code assumes that when you ask for rest.php?q=civicrm/foo/get you want the civicrm_foo_get function in api/v2/Foo.php. You can also ask for rest.php?q=civicrm/foo_bar/get and you'll end up with the civicrm_foo_bar_get function in api/v2/FooBar.php. It requires that you always have exactly 3 arguments.

This works fine for many functions, but it breaks on some important ones too. For instance, it works on civicrm_activity_create (as q=civicrm/activity/create) but doesn't work on civicrm_activity_get_contact (as q=civicrm/activity_get/contact). But that second format does work for civicrm_group_contact_add (as q=civicrm/group_contact/add). It's also putting resource type names and operation identifiers all over the place with little consistency.

So currently there's no way to automatically convert a method name to a URL because the naming is somewhat arbitrary. If we could define some simple rules for it, it would make using the API a much more pleasant experience (both directly and because it would enable the writing of simpler, more future-proof client libraries).

Ideally we would have a true REST interface (URLs are resources, operations are represented by the HTTP verb sent, etc.) but that would be a lot of work. So for now I'd suggest the following convention:

1. All API function names begin with civicrm_ like they do now.
2. The next part of the function name represents the resource type and is an underscore-separated representation of the php filename in which the function resides (so that civicrm_foo_bar_get MUST be defined in api/v2/FooBar.php because "foo_bar" is converted to "FooBar".
3. The last part of the function name represents the operation (i.e. "get", "delete", "create", etc.). This part MAY NOT contain an underscore (otherwise it would be very hard to tell where you switched from resource type to operation identifier when parsing).

Then, when generating URLs, you stick to the requirement that only ever be 3 slash-separated arguments, and the first one is always "civicrm". So you always have rest.php?q=civicrm/ at the beginning. Then in the 2nd argument you put in the underscore-separated resource type / filename identifier. In the 3rd and last part you put in the operation identifier.

So for our two slightly more complex examples above, you'd have to rename the civicrm_activity_get_contact function to civicrm_activity_contact_get and put it in a separate file called api/v2/ActivityContact.php. It would just work for civicrm_group_contact_add since that follows these rules already.

Does this seem like a reasonable requirement to impose? We could write backwards-compatibility wrapper functions to call the new ones (and ideally spit out a deprecation warning) anywhere we had to rename a function.

I've posted this to the wiki here: http://wiki.civicrm.org/confluence/pages/viewpage.action?pageId=15401593

That's a straightforward approach.  But, one of the goals of an API definition is to maintain a consistent way to talk to the system as the system internals change.  In other words, if we treat a "resource" in the above definition as just the external representation of a BAO, we introduce two problems:

• Any system internal change that affects BAO definitions will appear to the outside as a change in the API definition
• Any DBMS operation that requires atomic access to more than one table will be hard to do through the API since multiple REST operations will be needed and there is not a way to guarantee atomicity of multiple operations.

So, we also need to think about how to handle those situations.

-- Walt
 

Wes, thanks for getting the ball rolling on these updates.  There are several factors I'd like to change about how the REST interface works that are separate from the API itself. I think it would be helpful if we talked about this as 2 parts: the API itself, the REST interface that wraps around it.  If we have consistent rules in the API, making them work sensibly over REST becomes much easier.  The REST interface has several sins in it that I would like to clean up (like returning multiple keys, unclear URL structure, everything is a GET, etc).  Some are my fault, some are inherited from the experimental interface I started with, but I'd like address as many as possible for 2.3.

I'll put together suggestions about that on the wiki soon, and provide a link here.  But unless others object, I'm inclined to think we should continue to treat the REST interface as just that; an interface to the underlying API.  Let's not get hung up here too much about the REST interface.  The API should be consistent no matter how you reach it.  I expect that it's no less frustrating if you're writing a module that works against a changing API than if you're working on an unrelated CMS.

I'm not clear on what exactly you're recommending here. Where are we getting "hung up" on the REST interface?

I think it's mainly that most of us who are interested in the API are also interested in the REST interface because that's how we want to access the API. So we want to work on / improve both at the same time. But I think we're doing a good job of maintaining the logical separation between the two. Do you disagree?

I think this conversation has been fine, but I think it'll be hard to maintain a separation of the two layers if they are discussed in the same place.

I don't think we're going to let the (perceived or real) shortcomings of the REST interface hold us back from improving and documenting the API, but we do want to address the shortcomings of the REST interface on the same or similar timeline. I'm inclined to let you take the lead on that now since you designed and built it and have good ideas for how to improve it. But there are also some ideas coming from this group (such as the more than one API call per REST call / transactional integrity idea) which are good and we'd like to at least discuss here. (Or, to be more correct, the use cases those ideas cover are valid and common and we should discuss how we will accommodate them in the REST interface at some point soon.) Seem right?

Yes.  I just want to make sure we pay attention to both sets of issues.  I think there are definitely issues that overlap, like Walt's comments you make reference too.  The two issues can't be handled totally independently, but I'm just worried that if you hold one conversation we'll lose details from one problem in the other.  I wasn't trying to shut anything down.

Jim Taylor left a comment on the wiki page making a suggestion about how to handle custom additions to the API.  I've been trying to think about ways that we might be able to address Walt's suggestion about making it possible to combine multiple API calls in one atomic REST call. 

Would it be reasonable to design a system that would allow for custom additions to the API that could be called through the REST interface as a means of handling Walt's idea?  If the REST interface called custom API add-ons, advanced users could then add functions to the API as needed.  Walt would this work for you, or do we need something else?  If not, can you give an example of what you're thinking of?