README.md in layervault-0.1.1 vs README.md in layervault-0.1.2

- old
+ new

@@ -42,62 +42,85 @@ ## Initializing the Client You can initialize the client via Environment Variables or by passing configurations options into the client when you create it, like this: - @client = LayerVault::Client.new(access_token: 'your_access_token', api_endpoint: 'your_api_endpoint') +``` ruby +@client = LayerVault::Client.new({ + access_token: 'your_access_token', + api_endpoint: 'your_api_endpoint' +}) +``` Or you can also say: - LayerVault.client.access_token = 'access_token' - LayerVault.client.api_endpoint = 'api_endpoint' +``` ruby +LayerVault.client.access_token = 'access_token' +LayerVault.client.api_endpoint = 'api_endpoint' +``` ### Environment Variables - ENV['LAYERVAULT_ACCESS_TOKEN'] - You LayerVault API access token - ENV['LAYERVAULT_API_ENDPOINT'] - The API Endpoint you wish to target calls against (defaults to `https://api.layervault.com/api/v1/`) - ENV['LAYERVAULT_USER_AGENT'] - Defaults to `LayerVault Ruby Gem #{LayerVault::VERSION}` +``` ruby +# You LayerVault API access token +ENV['LAYERVAULT_ACCESS_TOKEN'] +# The API Endpoint you wish to target calls against (defaults to https://api.layervault.com/api/v1/) +ENV['LAYERVAULT_API_ENDPOINT'] + +# Defaults to LayerVault Ruby Gem #{LayerVault::VERSION} +ENV['LAYERVAULT_USER_AGENT'] +``` + ### The User Agent You should set the User agent to include your email address so that in the event your client does something wrong we can contact you. ## Making API calls You can use the `LayerVault.client.<api_operation>` methods to call the API to perform actions. Alternatively, each API object has simple object model that allows you to say: +``` ruby +LayerVault.client.access_token = 'access_token' +p = LayerVault::Organization.for('layervault') +p.create_project('my new project') ``` - LayerVault.client.access_token = 'access_token' - p = LayerVault::Organization.for('layervault') - p.create_project('my new project') -``` -And so on. +And so on. An example of using the Simple Object Model looks like: +```ruby +2.0.0-p247 :003 > revision = LayerVault::Revision.for("kellys-second-dropbox-test-org", 'Third Project', '', 'Grîeps.psd', 1) + => #<LayerVault::Revision context=#<LayerVault::Revision file_name="Grîeps.psd" folder_path="" organization="kellys-second-dropbox-test-org" project="Third Project" revision=1> deleted_at=nil download_url="https://layervault.com/files/download_node/BghUzqVDpJ" full_url="https://layervault.com/kellys-second-dropbox-test-org/Third%20Project/Gr%C3%AEeps.psd" local_path="~/LayerVault/Third Project/Grîeps.psd" md5=nil modified_at="2013-11-22T01:59:11Z" name="Grîeps.psd" revision_number=4 revisions=[#<LayerVault::Revision created_at="2013-11-20T23:24:54Z" download_url="https://layervault.com/files/download_node/QH1QqU1SjS" full_url="https://layervault.com/kellys-second-dropbox-test-org/Third%20Project/Gr%C3%AEeps.psd/1" id=nil md5=nil revision_number=1 shortened_url="http://lyrv.lt/QH1QqU1SjS" tree_revision_id=732917 updated_at="2013-11-20T23:25:16Z">, #<LayerVault::Revision created_at="2013-11-20T23:25:30Z" download_url="https://layervault.com/files/download_node/7xXIVAriIQ" full_url="https://layervault.com/kellys-second-dropbox-test-org/Third%20Project/Gr%C3%AEeps.psd/2" id=nil md5=nil revision_number=2 shortened_url="http://lyrv.lt/7xXIVAriIQ" tree_revision_id=732922 updated_at="2013-11-20T23:26:02Z">, #<LayerVault::Revision created_at="2013-11-20T23:26:07Z" download_url="https://layervault.com/files/download_node/InR5lHOx6k" full_url="https://layervault.com/kellys-second-dropbox-test-org/Third%20Project/Gr%C3%AEeps.psd/3" id=nil md5=nil revision_number=3 shortened_url="http://lyrv.lt/InR5lHOx6k" tree_revision_id=732926 updated_at="2013-11-20T23:26:30Z">, #<LayerVault::Revision created_at="2013-11-22T01:59:11Z" download_url="https://layervault.com/files/download_node/BghUzqVDpJ" full_url="https://layervault.com/kellys-second-dropbox-test-org/Third%20Project/Gr%C3%AEeps.psd/4" id=nil md5=nil revision_number=4 shortened_url="http://lyrv.lt/BghUzqVDpJ" tree_revision_id=737792 updated_at="2013-11-22T01:59:33Z">] shortened_url="http://lyrv.lt/sDNUs3aXGR" updated_at="2013-11-22T01:59:33Z"> +2.0.0-p247 :004 > revision.preview(100,100) + => "\"https://layervault-preview.imgix.net/data/9c09ef898aaf600ee3f9750b8aa6157a?w=100&h=100&s=998b23bd5d90d105a9b2a4c3ef082506\"" + ``` + ### Simple Object Model There's a very simple object model provided by classes that implement [Hashie](https://github.com/intridea/hashie) objects that wrap the JSON responses from the ```LayerVault.client``` interface. The objects mostly all follow a ```.for``` pattern that accepts the appropriate number of arguments for the level of nesting the object represents. For example, - - Organizations require the name of the organization: ```Organization.for('layervault')``` - - Projects require the name of the organization and the project name: ```Project.for('layervault', 'Designer News')``` + - Organizations require the permalink of the organization: ```Organization.for('layervault')``` + - Projects require the permalink of the organization and the project name: ```Project.for('layervault', 'Designer News')``` - ... and so on ... #### Associations -When using the simple object model, associations will be hydrated into the correct child objects allowing a simple level of traversal down the object model hierarchy. +When using the simple object model, associations will be hydrated into the correct child objects for the immediate child relationships only, allowing a simple level of traversal down the object model hierarchy. There is no lazy loding support that will automatically hydrated any deeper associations - you must perform new queries. ## Access Tokens Access Tokens are valid for two hours only. When you request a token, you are also told how long the token is valid for, in seconds, as part of the token response: - { - "access_token": "aec9c670cf5e673bfedf83d055d2a2e0e5f37e52d3b41cffcf7874f73a7458bf", - "token_type": "bearer", - "expires_in": 7200, - "refresh_token": "afe9c670cf5e673bfedf83d055d2a2e0e5f37e52d3b41cffcf7874f73a7458bf", - "scope": "user" - } +``` json +{ + "access_token": "aec9c670cf5e673bfedf83d055d2a2e0e5f37e52d3b41cffcf7874f73a7458bf", + "token_type": "bearer", + "expires_in": 7200, + "refresh_token": "afe9c670cf5e673bfedf83d055d2a2e0e5f37e52d3b41cffcf7874f73a7458bf", + "scope": "user" +} +``` Here we can see that the Token is valid for 7200 more seconds, or two hours. The API implements [Refresh Tokens](https://github.com/applicake/doorkeeper/wiki/Enable-Refresh-Token-Credentials) which allow you to request new tokens without re-authenticating the user through the Web credentials flow. You can see in the access token response above, a refresh_token was given for use in future calls. Store it, use it. @@ -118,34 +141,36 @@ ### General - LayerVault.client.me ### Organizations - - LayerVault.client.organization( organization_name ) + - LayerVault.client.organization( organization_permalink ) ### Projects - - LayerVault.client.project( organization_name, project ) - - LayerVault.client.create_project( organization_name, project ) - - LayerVault.client.delete_project( organization_name, project ) - - LayerVault.client.move_project( organization_name, project, to ) - - LayerVault.client.change_project_folder_color( organization_name, project, color ) + - LayerVault.client.project( organization_permalink, project ) + - LayerVault.client.create_project( organization_permalink, project ) + - LayerVault.client.delete_project( organization_permalink, project ) + - LayerVault.client.move_project( organization_permalink, project, to ) + - LayerVault.client.change_project_folder_color( organization_permalink, project, color ) ### Folders - - LayerVault.client.folder( organization_name, project, folder_path ) - - LayerVault.client.create_folder( organization_name, project, folder_path ) - - LayerVault.client.delete_folder( organization_name, project, folder_path ) - - LayerVault.client.move_folder( organization_name, project, folder_path, new_folder ) - - LayerVault.client.change_folder_color( organization_name, project, folder_path, color ) + - LayerVault.client.folder( organization_permalink, project, folder_path ) + - LayerVault.client.create_folder( organization_permalink, project, folder_path ) + - LayerVault.client.delete_folder( organization_permalink, project, folder_path ) + - LayerVault.client.move_folder( organization_permalink, project, folder_path, new_folder ) + - LayerVault.client.change_folder_color( organization_permalink, project, folder_path, color ) ### Files - - LayerVault.client.file( organization_name, project, folder_path, file_name ) - - LayerVault.client.create_file( organization_name, project, folder_path, file_name, options ) - - LayerVault.client.delete_file( organization_name, project, folder_path, file_name ) - - LayerVault.client.move_file( organization_name, project, folder_path, new_folder, new_filename ) - - LayerVault.client.sync_check( organization_name, project, folder_path, options ) + - LayerVault.client.file( organization_permalink, project, folder_path, file_name ) + - LayerVault.client.create_file( organization_permalink, project, folder_path, file_name, options ) + - LayerVault.client.delete_file( organization_permalink, project, folder_path, file_name ) + - LayerVault.client.move_file( organization_permalink, project, folder_path, new_folder, new_filename ) + - LayerVault.client.sync_check( organization_permalink, project, folder_path, options ) + - LayerVault.client.previews( organization_permalink, project, folder_path, file_name, options ) + - LayerVault.client.revisions( organization_permalink, project, folder_path, file_name, options ) ### Revisions - - LayerVault.client.revision( organization_name, project, folder_path, file_name, revision ) - - LayerVault.client.previews( organization_name, project, folder_path, file_name, revision, options ) - - LayerVault.client.revisions( organization_name, project, folder_path, file_name, revision, options ) - - LayerVault.client.meta( organization_name, project, folder_path, file_name, revision ) + - LayerVault.client.revision( organization_permalink, project, folder_path, file_name, revision ) + - LayerVault.client.preview( organization_permalink, project, folder_path, file_name, revision, options ) + - LayerVault.client.meta( organization_permalink, project, folder_path, file_name, revision ) + - LayerVault.client.feedback_items( organization_permalink, project, folder_path, file_name, revision )