I’m creating a PHP library for a third-party site’s REST API. The library will be released under an appropriate FOSS license so others may use it. The third-party site has APIs for both authenticated and unauthenticated requests. For authenticated requests, they’ve chosen OAuth.
As with most things PHP, there is no one single best way to work with OAuth. So far, I’ve identified a handful of OAuth implementations:
- PECL’s OAuth extension, almost considered “1.0” quality.
- PEAR’s HTTP_OAuth, but it’s still considered “alpha” quality.
- Zend Framework’s Zend_Oauth, pretty stable and doesn’t require the app be written using ZF.
- oauth-php, the top Google hit for
php oauth.
The variety of available libraries is problem. A major part of OAuth 1 is signing the request. This means that in order to make a request to the REST API, I have to go through one of the libraries. I’m trying to avoid bundling one of the OAuth libraries with my code, and simply allow coders that will use the library to pick which OAuth library to use in their own code. I consider this important because of how complex OAuth can be to understand for some coders, and it’s very important that the coder using my library be comfortable and familiar with OAuth.
I’ve done this by creating an Interface designed to wrap the OAuth objects and present a standardized way for my library code to make signed HTTP requests. So far I’ve created support for the PECL, PEAR and Zend libraries, with the oauth-php library next on the list. Because the API also allows unauthenticated requests, I’ve also created adapters for PHP streams and HTTP request libraries that the PEAR and Zend packages require. (PHP streams are used by default without any configuration needed, because they’re built in and guaranteed to be available.)
This has ended up being a non-trivial amount of work and makes the code look far more complex and imposing than it really is. The code Just Works(tm), and doing that requires a lot of magic (like automatically picking the HTTP adapter based on the class name of the passed OAuth object; this also allows users to create their own adapters without changing the library).
I’m beginning to think that it might be better to bundle an OAuth library with my code. OAuth is defined by an RFC, and all of the linked libraries implement it correctly. I can simply have the user provide the various keys/secrets/tokens and do the work myself, at the cost of adding a requirement of an entire OAuth implementation that the user did not pick. That’s a big downside, in my opinion. Further, there’s a question of license compatibility. The library I’d have to pick is available under a very liberal FOSS license, while I’d prefer a more restrictive FOSS license for my own code.
tl;dr: For a reusable library, should I continue using pluggable HTTP adapters and letting the user decide which OAuth library (or non-OAuth HTTP library) to use, or should I decide for the user and simply bundle another library with my own?
Depends on the amount of work it entails versus the benefits. It must be you who has to do such evaluation, taking into consideration the needs of your (actual or potential) user base.
As to the licensing part, you shouldn’t have any problem creating an adapter for any library unless it uses a GPL license (LGPL shouldn’t be a problem). But anyway, if that is a problem, you could just bundle the adapters for the libraries that have a liberal license, like the PECL one (you can do whatever you want with it, including modifying it and not publish those changes). You could then provide, separately, the adapters for the GPL ones under a GPL license.
I am not a lawyer, though! Consult with one to be sure.