renanbr / crossref-client
Client for CrossRef REST API
Installs: 23 935
Dependents: 0
Suggesters: 0
Security: 0
Stars: 5
Watchers: 2
Forks: 4
Open Issues: 2
Requires
- php: >=5.6.0
- cache/array-adapter: ^1.0
- cache/simple-cache-bridge: ^1.0
- composer/semver: ^3.3
- guzzlehttp/guzzle: ^6.2 || ^7.4
- kevinrob/guzzle-cache-middleware: ^3.1 || ^4.0
- psr/simple-cache: ^1.0 || ^2.0 || ^3.0
- rtheunissen/guzzle-rate-limiter: ^1.0 || ^2.0
Requires (Dev)
- phpunit/phpunit: >=5.7
README
This is a library for the Crossref REST API written in PHP.
Table of contents
Introduction
This is NOT an official library! The intent of this library is to provide an easy way to make requests to the CrossRef's REST API. You SHOULD read this documentation in conjunction with the official documentation.
Highlighted features:
- You don't need to worry about making HTTP requests;
- Proper exceptions are thrown if an HTTP error occurs;
- You receive responses as-is, without overlay;
- Filter and facet parameters are encoded if needed;
- You can cache responses easily;
- You can identify yourself, then you can benefit better service;
- You can tie to a specific major version of the API;
- Your application complies with the rate limit (it works better if cache is configured).
Library's summary:
class RenanBr\CrossRefClient { // Returns JSON decoded as array public function request($path, array $parameters = []); // Returns boolean public function exists($path); public function setUserAgent($userAgent); public function setCache(Psr\SimpleCache\CacheInterface $cache); public function setVersion($version); }
Installing
composer require renanbr/crossref-client ^1
Usage
Singletons
Singletons are single results. Retrieving metadata for a specific identifier (e.g. DOI, ISSN, funder_identifier) typically returns in a singleton result.
See: https://github.com/CrossRef/rest-api-doc#singletons
require __DIR__ . '/vendor/autoload.php'; $client = new RenanBr\CrossRefClient(); $work = $client->request('works/10.1037/0003-066X.59.1.29'); print_r($work);
The above example will output:
Array
(
[status] => ok
[message-type] => work
[message-version] => 1.0.0
[message] => Array
(
...
[DOI] => 10.1037/0003-066x.59.1.29
[type] => journal-article
...
[title] => Array
(
[0] => How the Mind Hurts and Heals the Body.
)
...
)
)
Determine existence of a singleton
(...) [You can] determine "existence" of a singleton. The advantage of this technique is that it is very fast because it does not return any metadata (...)
See: https://github.com/CrossRef/rest-api-doc#headers-only
require __DIR__ . '/vendor/autoload.php'; $client = new RenanBr\CrossRefClient(); $exists = $client->exists('members/98'); var_dump($exists);
The above example will output:
bool(true)
Lists
Lists results can contain multiple entries. Searching or filtering typically returns a list result.
A list has two parts: Summary; and Items. Normally, an API list result will return both.
See: https://github.com/CrossRef/rest-api-doc#lists
require __DIR__ . '/vendor/autoload.php'; $client = new RenanBr\CrossRefClient(); $parameters = [ 'query' => 'global state', 'filter' => [ 'has-orcid' => true, ], ]; $result = $client->request('works', $parameters); foreach ($result['message']['items'] as $work) { // ... }
Configuration
Caching results
Cache data so you don't request the same data over and over again.
See: https://github.com/CrossRef/rest-api-doc#etiquette
require __DIR__ . '/vendor/autoload.php'; $client = new RenanBr\CrossRefClient(); $client->setCache(new voku\cache\CachePsr16()); // ...
The above example uses voku/simple-cache as cache implementation, but you can use any PSR-16 implementation because setCache()
accept Psr\SimpleCache\CacheInterface as argument.
Identifying your script
As of September 18th 2017 any API queries that use HTTPS and have appropriate contact information will be directed to a special pool of API machines that are reserved for polite users.
See: https://github.com/CrossRef/rest-api-doc#good-manners--more-reliable-service
require __DIR__ . '/vendor/autoload.php'; $client = new RenanBr\CrossRefClient(); $client->setUserAgent('GroovyBib/1.1 (https://example.org/GroovyBib/; mailto:GroovyBib@example.org)'); // ...
The above example makes all subsequent requests attach the contact information given.
Tying to a specific major version
If you need to tie your implementation to a specific major version of the API, you can do so by using version-specific routes. The default route redirects to the most recent version of the API.
See: https://github.com/CrossRef/rest-api-doc#how-to-manage-api-versions
require __DIR__ . '/vendor/autoload.php'; $client = new RenanBr\CrossRefClient(); $client->setVersion('v55'); // ...
The above example tie all subsequent requests to the API version v55
.
Rate limits
By default, this library conforms to the rate limit imposed by the API for the current execution.
If you want to keep this behavior across multiple executions, you must configure the cache, as mentioned above.
Handling errors
As this library uses guzzlehttp/guzzle internally. Please refer to the Guzzle Exceptions documentation to see how to handle exceptions properly.