Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Update master

  • Loading branch information...
commit 4521795c1764920c380d28d5461ad56272b64c78 1 parent 3d5d540
Neil Mansilla mansilladev authored
Showing with 69 additions and 24 deletions.
  1. +69 −24 README.md
93 README.md
View
@@ -1,24 +1,69 @@
-io-wraps-usatoday-php
-=====================
-v0.5 - PHP wrapper for USA TODAY Articles and Census API.
-
-Unpack this package into a directory at the "htdocs" level on any
-web server stack with PHP. The references to the dependences are
-all relative.
-
-1. The three functional PHP examples are articles_headlines.php,
-community_feed.php and census_population.php. These are live
-examples, not the libraires. To see how the libraries are used,
-just peek at the source.
-
-2. Add your key to these source files to make calls. Both
-articles_headlines and community_feed will use your USA TODAY
-Articles API key. census_population will require your USA TODAY
-Census API key.
-
-3. Navigate to articles_headlines.php, community_feed.php and
-census_population.php from your browser and give it a whirl.
-
-Requirements: Any standard LAMP stack. PHP requirements are
-the regular suspects. Please report any dependency issues along
-with a stack bio (OS, server, etc.).
+# USA TODAY API Client Library for PHP
+###PHP client libraries created with Mashery I/O Wraps, a semi-automated native language SDK generator.
+
+## What is the USA TODAY API?
+USA TODAY offers content APIs that allow developers to access their resources, such as news articles, book reviews, best seller lists (books), census data, movie reviews, music reviews and much more. Head over to [developer.usatoday.com](http://developer.usatoday.com) to learn more. You can register for instant access to their API, view their documentation, and even make live API calls with their interactive docs.
+
+## Summary
+An API client library (also known as an SDK or language wrapper) is an efficiency tool for programmer that helps bind external resources to your native programming language. Traditionally, to integrate an API into your project without a client library, you would need to do the following:
+
+1. Construct a network request using a transport library (e.g. HTTP)
+
+2. Integrate authentication flow and signatures (e.g. OAuth, MD5/SHA-256, etc.)
+
+3. Construct and execute API calls manually, often a trial and error process while reading documentation
+
+4. Parse through results
+
+5. Lather. Rinse. Repeat.
+
+## How does the client library help?
+Client libraries make life easier by bringing the API into your native language environment. So, rather than making curl calls, piping the output into a variable, and parsing through the variable -- the client library handles the network connectivity, authorization and API call execution with syntax you're familiar with:
+
+ // Initialize the client library
+ $client = new apiClient();
+
+ // Set your API key
+ $client->setDeveloperKey("YOUR_KEY_HERE");
+
+ // Connect client to the API
+ $api = new apiService($client);
+
+ // Make an API call and store the response in an object
+ $StoryList = new StoryList($api -> ArticleMethods -> TopNews ("json","sports"));
+
+ // Iterate through the list of stories, and echo the titles
+ foreach ($StoryList->getStories() as $story) {
+ echo("Title: " . $story->getTitle());
+ }
+
+Above is just a pseudo-PHP-code example of how this library works. If you'd like to see it in action, check out the example PHP files in this repo.
+
+## Requirements
+1. PHP - if you'd like a quick a dirty isolated LAMP stack, check out [XAMPP](http://www.apachefriends.org/en/xampp.html). Works on Mac, PC and even Linux.
+2. USA TODAY API key -- head over to [http://developer.usatoday.com](http://developer.usatoday.com)
+
+## IDE is optional, but nice
+At Mashery, we love [vim](http://www.vim.org) just as much as the next guy, but when it comes to tool-tips, code-completion and general object-oriented goodness, IDEs can be really useful. [Eclipse](http://eclipse.org), [Aptana](http://aptana.com), [Netbeans](http://netbeans.org), [Komodo](http://www.activestate.com/komodo-ide), etc. They're all very mature and useful tools.
+
+## Installation / Quick Start Guide
+Follow the steps below for a quick start to using this client library:
+
+1. Grab the latest source with git.
+
+ <pre>git clone git://github.com/mashery/io-wrap-usatoday-php.git</pre>
+
+2. Move the project source tree into your sandbox LAMP stack environment (anywhere below the httpdocs/htdocs level -- example code is relatively linked)
+
+3. Head over to [USA TODAY Developer Network](http://developer.usatoday.com) to fetch an API key
+
+4. Open up your editor and add your API key where you see *YOUR_KEY_HERE* on the sample PHP scripts.
+
+5. Point your browser to one of the example files where this is deployed:
+
+ <pre>Ex: http://localhost/io-wrap-whitli-php/whitli_get_key.php</pre>
+
+## About / License
+* No warranty expressed or implied. Software as is.
+* [MIT License](http://www.opensource.org/licenses/mit-license.html)
+* Lovingly created by [Mashery Dev](http://dev.mashery.com)
Please sign in to comment.
Something went wrong with that request. Please try again.