X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/1601c616fe494b50de98cec4c4bfdb0713ce7246..a53bf7d89e01e98dcdc62b5357a0404d5489c9a1:/README.md diff --git a/README.md b/README.md index 048723fb04..fced2eb5b7 100644 --- a/README.md +++ b/README.md @@ -1,181 +1,96 @@ -# Google API Client +[comment]: # (Copyright © The Arvados Authors. All rights reserved.) +[comment]: # () +[comment]: # (SPDX-License-Identifier: CC-BY-SA-3.0) -
-
Homepage
http://code.google.com/p/google-api-ruby-client
-
Authoris
Bob Aman, Steven Bazyl
-
Copyright
Copyright © 2011 Google, Inc.
-
License
Apache 2.0
-
+[![Join the chat at https://gitter.im/arvados/community](https://badges.gitter.im/arvados/community.svg)](https://gitter.im/arvados/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) | [Installing Arvados](https://doc.arvados.org/install/index.html) | [Installing Client SDKs](https://doc.arvados.org/sdk/index.html) | [Report a bug](https://dev.arvados.org/projects/arvados/issues/new) | [Development and Contributing](CONTRIBUTING.md) -[![Build Status](https://secure.travis-ci.org/google/google-api-ruby-client.png)](http://travis-ci.org/google/google-api-ruby-client) -[![Dependency Status](https://gemnasium.com/google/google-api-ruby-client.png)](https://gemnasium.com/google/google-api-ruby-client) + -## Description +[Arvados](https://arvados.org) is an open source platform for +managing, processing, and sharing genomic and other large scientific +and biomedical data. With Arvados, bioinformaticians run and scale +compute-intensive workflows, developers create biomedical +applications, and IT administrators manage large compute and storage +resources. -The Google API Ruby Client makes it trivial to discover and access supported -APIs. +The key components of Arvados are: -## Install +* *Keep*: Keep is the Arvados storage system for managing and storing large +collections of files. Keep combines content addressing and a +distributed storage architecture resulting in both high reliability +and high throughput. Every file stored in Keep can be accurately +verified every time it is retrieved. Keep supports the creation of +collections as a flexible way to define data sets without having to +re-organize or needlessly copy data. Keep works on a wide range of +underlying filesystems and object stores. -Be sure `http://rubygems.org/` is in your gem sources. +* *Crunch*: Crunch is the orchestration system for running [Common Workflow Language](https://www.commonwl.org) workflows. It is +designed to maintain data provenance and workflow +reproducibility. Crunch automatically tracks data inputs and outputs +through Keep and executes workflow processes in Docker containers. In +a cloud environment, Crunch optimizes costs by scaling compute on demand. -For normal client usage, this is sufficient: +* *Workbench*: The Workbench web application allows users to interactively access +Arvados functionality. It is especially helpful for querying and +browsing data, visualizing provenance, and tracking the progress of +workflows. - $ sudo gem install google-api-client +* *Command Line tools*: The command line interface (CLI) provides convenient access to Arvados +functionality in the Arvados platform from the command line. -The command line interface, the example applications, and the test suite -require additional dependencies. These may be obtained with: +* *API and SDKs*: Arvados is designed to be integrated with existing infrastructure. All +the services in Arvados are accessed through a RESTful API. SDKs are +available for Python, Go, R, Perl, Ruby, and Java. - $ sudo gem install google-api-client --development --force --no-rdoc --no-ri +# Quick start -## Example Usage +To try out Arvados on your local workstation, you can use Arvbox, which +provides Arvados components pre-installed in a Docker container (requires +Docker 1.9+). After cloning the Arvados git repository: - # Initialize the client & Google+ API - require 'google/api_client' - client = Google::APIClient.new - plus = client.discovered_api('plus') +``` +$ cd arvados/tools/arvbox/bin +$ ./arvbox start localdemo +``` - # Initialize OAuth 2.0 client - client.authorization.client_id = '' - client.authorization.client_secret = '' - client.authorization.redirect_uri = '' - - client.authorization.scope = 'https://www.googleapis.com/auth/plus.me' +In this mode you will only be able to connect to Arvbox from the same host. To +configure Arvbox to be accessible over a network and for other options see +http://doc.arvados.org/install/arvbox.html for details. - # Request authorization - redirect_uri = client.authorization.authorization_uri +# Documentation - # Wait for authorization code then exchange for token - client.authorization.code = '....' - client.authorization.fetch_access_token! +Complete documentation, including the [User Guide](https://doc.arvados.org/user/index.html), [Installation documentation](https://doc.arvados.org/install/index.html), [Administrator documentation](https://doc.arvados.org/admin/index.html) and +[API documentation](https://doc.arvados.org/api/index.html) is available at http://doc.arvados.org/ - # Make an API call - result = client.execute( - :api_method => plus.activities.list, - :parameters => {'collection' => 'public', 'userId' => 'me'} - ) +If you wish to build the Arvados documentation from a local git clone, see +[doc/README.textile](doc/README.textile) for instructions. - puts result.data +# Community -## API Features +[![Join the chat at https://gitter.im/arvados/community](https://badges.gitter.im/arvados/community.svg)](https://gitter.im/arvados/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) -### API Discovery +The [Arvados community channel](https://gitter.im/arvados/community) +channel at [gitter.im](https://gitter.im) is available for live +discussion and support. -To take full advantage of the client, load API definitions prior to use. To load an API: +The [Arvados developement channel](https://gitter.im/arvados/development) +channel at [gitter.im](https://gitter.im) is used to coordinate development. - urlshortener = client.discovered_api('urlshortener') +The [Arvados user mailing list](http://lists.arvados.org/mailman/listinfo/arvados) +is used to announce new versions and other news. -Specific versions of the API can be loaded as well: +All participants are expected to abide by the [Arvados Code of Conduct](CODE_OF_CONDUCT.md). - drive = client.discovered_api('drive', 'v2') +# Reporting bugs -Locally cached discovery documents may be used as well. To load an API from a local file: +[Report a bug](https://dev.arvados.org/projects/arvados/issues/new) on [dev.arvados.org](https://dev.arvados.org). - doc = File.read('my-api.json') - my_api = client.register_discovery_document('myapi', 'v1', doc) +# Development and Contributing -### Authorization - -Most interactions with Google APIs require users to authorize applications via OAuth 2.0. The client library uses [Signet](https://github.com/google/signet) to handle most aspects of authorization. For additional details about Google's OAuth support, see [Google Developers](https://developers.google.com/accounts/docs/OAuth2). - -Credentials can be managed at the connection level, as shown, or supplied on a per-request basis when calling `execute`. - -For server-to-server interactions, like those between a web application and Google Cloud Storage, Prediction, or BigQuery APIs, use service accounts. - - key = Google::APIClient::KeyUtils.load_from_pkcs12('client.p12', 'notasecret') - client.authorization = Signet::OAuth2::Client.new( - :token_credential_uri => 'https://accounts.google.com/o/oauth2/token', - :audience => 'https://accounts.google.com/o/oauth2/token', - :scope => 'https://www.googleapis.com/auth/prediction', - :issuer => '123456-abcdef@developer.gserviceaccount.com', - :signing_key => key) - client.authorization.fetch_access_token! - client.execute(...) - - -### Batching Requests - -Some Google APIs support batching requests into a single HTTP request. Use `Google::APIClient::BatchRequest` -to bundle multiple requests together. - -Example: - - client = Google::APIClient.new - urlshortener = client.discovered_api('urlshortner') - - batch = Google::APIClient::BatchRequest.new do |result| - puts result.data - end - - batch.add(:api_method => urlshortener.url.insert, - :body_object => { 'longUrl' => 'http://example.com/foo' }) - batch.add(:api_method => urlshortener.url.insert, - :body_object => { 'longUrl' => 'http://example.com/bar' }) - client.execute(batch) - -Blocks for handling responses can be specified either at the batch level or when adding an individual API call. For example: - - batch.add(:api_method=>urlshortener.url.insert, :body_object => { 'longUrl' => 'http://example.com/bar' }) do |result| - puts result.data - end - -### Media Upload - -For APIs that support file uploads, use `Google::APIClient::UploadIO` to load the stream. Both multipart and resumable -uploads can be used. For example, to upload a file to Google Drive using multipart - - drive = client.discovered_api('drive', 'v2') - - media = Google::APIClient::UploadIO.new('mymovie.m4v', 'video/mp4') - metadata = { - 'title' => 'My movie', - 'description' => 'The best home movie ever made' - } - client.execute(:api_method => drive.files.insert, - :parameters => { 'uploadType' => 'multipart' }, - :body_object => metadata, - :media => media ) - -To use resumable uploads, change the `uploadType` parameter to `resumable`. To check the status of the upload -and continue if necessary, check `result.resumable_upload`. - - client.execute(:api_method => drive.files.insert, - :parameters => { 'uploadType' => 'resumable' }, - :body_object => metadata, - :media => media ) - upload = result.resumable_upload - - # Resume if needed - if upload.resumable? - client.execute(upload) - end - -## Command Line - -Included with the gem is a command line interface for working with Google APIs. - - # Log in - google-api oauth-2-login --client-id='...' --client-secret='...' --scope="https://www.googleapis.com/auth/plus.me" - - # List the signed-in user's activities - google-api execute plus.activities.list --api=plus -- userId="me" collection="public" - - # Start an interactive API session - google-api irb - >> plus = $client.discovered_api('plus') - >> $client.execute(plus.activities.list, {'userId' => 'me', 'collection' => 'public'}) - => # returns a response from the API - -For more information, use `google-api --help` - -## Samples - -See the full list of [samples on Google Code](http://code.google.com/p/google-api-ruby-client/source/browse?repo=samples). - - -## Support - -Please [report bugs at the project on Google Code](http://code.google.com/p/google-api-ruby-client/issues/entry). Don't hesitate to [ask questions](http://stackoverflow.com/questions/tagged/google-api-ruby-client) about the client or APIs on [StackOverflow](http://stackoverflow.com). +See [CONTRIBUTING](CONTRIBUTING.md) for information about Arvados development and how to contribute to the Arvados project. +The [development road map](https://dev.arvados.org/issues/gantt?utf8=%E2%9C%93&set_filter=1&gantt=1&f%5B%5D=project_id&op%5Bproject_id%5D=%3D&v%5Bproject_id%5D%5B%5D=49&f%5B%5D=&zoom=1) outlines some of the project priorities over the next twelve months. +# Licensing +Arvados is Free Software. See [COPYING](COPYING) for information about the open source licenses used in Arvados.