 scripting Galaxy using the API and Bioblend. Before diving into this slide deck, we recommend you to have a look at the following. What is a REST API? How to interact with Galaxy programmatically? Why and when should I use Bioblend? An application programming interface provides software developers with a definition of the methods to interact with a program or a library. When the program is a remote web server like Galaxy, the methods are represented by URLs and the communication is through the HTTP protocol. Nowadays, most of the Galaxy user interface makes use of the back-end API to implement an asynchronous web application. The Galaxy user interface is a better choice for explorative analysis, visualizing data and drawing workflows. The API instead allows you to automate tasks using Galaxy's capabilities programmatically. A typical use case is to upload fast queue files as soon as your sequence of finishes writing them and running a quality control workflow. Importantly, however you interact with Galaxy, you can equally benefit from features like reproducibility of the analysis and data sharing. In fact, all the work done via the API is still accessible when you return to the UI. Most of the operations you would normally perform on the Galaxy UI are available via the API. You can for example upload data, run tools and workflows, and manage your histories. It is also possible to perform admin tasks like manage data libraries and install tools. The Galaxy API follows the REST model typical of web applications. A REST API specifies a protocol for the interaction between a client and a server. The client sends requests composed by an HTTP method and a resource. The main HTTP methods are get, to retrieve a resource, post, to create, put, to replace, and delete. Resources are identified by uniform resource identifiers. Examples of resources for the Galaxy API are data sets, tools, jobs, histories, libraries, users, essentially anything that is recorded in the Galaxy database. The client often need to pass additional parameters or data to specify how a request should be carried out. The server applies to the request with a status code to indicate if there was an error and usually some data. Let's see some examples of possible API requests to a Galaxy server. In the first example we use the get method to retrieve a resource. In this case the list of histories, the URI starts with the protocol and address of the server, followed by the resource we are interested in. The histories, a URI may then include an optional query, preceded by a question mark, containing a sequence of request parameters specified as key equal value and separated by ampersands. In this example, the query is used to ask that the list of histories is ordered by name. In the second example, the post method is used to create a resource on the server, in this case a new history. Parameters for the post request are passed as a payload in JSON format, more on this later. In this example the payload contains the new name for the history to be created. In the third example, we use the put method to update an existing resource. In this case to make a history public, the history to modify is identified by appending its ID to the histories URI. The parameters for put requests are also passed in a payload. In the fourth example, we use the delete method to remove a resource from the server. In this case, we request the deletion of a particular dataset in a specific history, as indicated in the URI. Request payloads passed to Galaxy and data returned by the API are encoded in the JSON format. JSON is a standard format used to exchange text data and is supported in all major programming languages. In JSON, strings are enclosed by double quotes, dictionaries by curly braces, and arrays by square brackets. Dictionaries and arrays can be nested at will, as shown in the example. In REST APIs, the server should use the standardized HTTP status codes in its responses to indicate either a successful request or the type of error encountered. In the Galaxy API, error status codes and messages are returned to the client by raising specific Python exceptions in the back end. A REST API can be accessed via the HTTP protocol. There are three main ways to do that. On the command line, the curl tool can perform any type of HTTP requests. Look at its manual for details. For graphical user interfaces, you can perform get requests directly on your browser by simply entering the URI on the address bar. For more complex requests, you can use the advanced REST client open source app. The third and most common way is to write a program. All programming languages have some general library to communicate over HTTP. For Python, requests is probably the best library to do that. Many web services provide dedicated higher level libraries to access their REST API. In particular, BioBlend is a Python library to interact with Galaxy that we will describe later. A note about security. When programmatically performing requests that require authentication, the client need to pass an API key. An API key is an alphanumeric string uniquely identifying a user on a server. Since it is equivalent to the combination of your username and password, keep it secure. In particular, always use the HTTPS protocol to make requests, not HTTP which sends data unencrypted. There are two options in the Galaxy configuration file that are relevant for the API. API underscore allow underscore run underscore as allows the specified user to impersonate any other user on the Galaxy instance. Master underscore API underscore key instead is an optional special API key that can be used to bootstrap a Galaxy instance, in particular to create an initial admin account. To summarize this first part, Galaxy has an extensive REST API that allows users and admins to interact programmatically with a server. It can be accessed with any programming language, but it's also very low level. For example, you need to construct complex URIs, encode payloads and decode returned data. A Python library called BioBlend was created in 2012 to make it easier to interact with the Galaxy API. BioBlend is open source and developed by a community of contributors. It is hosted on GitHub and can be installed via pip. BioBlend has a very stable procedural API and works on all supported Python versions. It provides methods wrapping all the important Galaxy API endpoints. The library uses continuous integration to perform a large number of tests on a wide range of Galaxy releases. The documentation of BioBlend is very well curated and is often more accurate than the corresponding Galaxy API one. Now it's a good time to try the Galaxy API and BioBlend. Follow the instructions on the slide to access the tutorials and exercises. Although easier to use than the Galaxy API, BioBlend has some limitations. First of all, it's only available for Python. There are alternative libraries for Java and PHP, but they are less complete. Another limitation of BioBlend is that it doesn't shield the caller from possible changes in responses from the Galaxy API. It can also be annoying to have to constantly keep track of entity IDs. This happens because BioBlend does not try to model Galaxy entities and how they are connected. To implement this modeling of Galaxy entities, some years ago an object-oriented interface was added on top of BioBlend. BioBlend underscore objects. It is developed and distributed together with BioBlend itself. When using this interface, method calls will return objects encapsulating the dictionaries returned by the Galaxy API. The user can then invoke further methods on these objects. For example the download method for a dataset object. Only a subset of BioBlend is available through the object interface, but most of the common user functionalities are included. Now you can try BioBlend underscore objects and see how it compares with BioBlend. Follow the instructions on the slide to access the tutorials and exercises. Here you can find the links to the documentation of the Galaxy API and of BioBlend. We have a dedicated Gitter channel to chat about BioBlend. If you use BioBlend or BioBlend underscore objects, please cite these papers. The API allows you to use Galaxy's capabilities programmatically. BioBlend makes using the Galaxy API from Python easier. BioBlend underscore objects is an object-oriented interface for interacting with Galaxy. Thank you for watching.