1. The EBI Search RESTful API
Programmatic access to EMBL-EBI
Rodrigo Lopez, Youngmi Park, Nicola Buso, Tamer Gur, Silvano Squizzato
Web Production team
Add photos
Team Meeting April 2016

2. Welcome - webinar instructions
GoToTraining works best in Chrome or IE
– avoid Firefox due to audio issues with Macs
To access the full features of GoToTraining, use the desktop version by clicking on the flower symbol and selecting “switch to desktop version”
All microphones will be muted whilst the trainer is speaking
If you have a question please use the chat box at the bottom of the GoToTraining box
Please complete the feedback survey which will launch at the end of the webinar.
This webinar is part of EMBL-EBI programmatic access webinar series.
We'll invite you to have a look at the 'introduction to programmatic access' webinar 

3. Summary Introduction to EBI Search
Overview of the EBI Search RESTful API
How to use the EBI Search RESTful API
Example 1: get domain metadata
Example 2: search and retrieval
Example 3: search with facets
Example 4: get cross-references
Help and support

4. Introduction to EBI Search

5. Web Production team at EMBL-EBI
The Web Production team is responsible for:
Web infrastructure & deployment
Job Dispatcher
EBI Search
The Web Production team is part of the Technical Services Cluster at EMBL-EBI.
Web Production areas: web platforms, web infrastructure and web deployment.
Job Dispatcher: analysis tool framework for job submission and result retrieval.

6. What is EBI Search?
A scalable fast text search, indexing and retrieval system
Enables powerful data navigation across the biological data at EMBL-EBI
EBI Search can be used:
over the web
programmatically using the RESTful API
Park Y.M., Squizzato S., Buso N., Gur T., Lopez R. (2017) The EBI search engine: EBI search as a service — making biological data accessible for all Nucleic Acids Research, May 2, 2017; doi: /nar/gkx359, PMID:

7. Why the RESTful API? The EBI Search RESTful API
allows users to search for data as input to other bioinformatics tools (workflows)
makes search capabilities available into third-party portals (Search as a Service)

8. EBI Search: Search as a Service
Structures
Proteins
Models
Literature
Genes
Flat files
XML
JSON
RESTful
API
Lucene Indexer
rnacentral.org
omicsdi.org
Data coverage:
- sequences
- genes
- gene products
- proteins
- protein families
- enzymes
- macromolecular structures
- diseases
- life science literature
A list of portals using the EBI Search RESTful API (Search as a Service) follows:
ENA:
Ensembl Genomes:
InterPro:
Expression Atlas:
RNAcentral:
Enzyme Portal:
OmicsDI:
PomBase:
HMMER:
Metagenomics :
EBI Search web interface:
During 2016, more than 362,000 unique IPs accessed EBI Search from across the globe.
These give rise to more than 300 million searches, comprising the web as well as usage of the RESTful API, and representing more than 1 TB of metadata downloaded that links search results with more than 1.3 billion records held in the databases at the EMBL–EBI.
EBI Search is based on Apache Lucene technology (

9. Overview on the EBI Search RESTful API

10. Where to find the RESTful API
Swagger interface:
Main source of documentation for the API
Interactive lab to test the API
WADL:
Binding contract for any client using the RESTful API
Base URL for RESTful API:
Swagger ( is the world’s largest framework of API developer tools for the OpenAPI Specification(OAS), enabling development across the entire API lifecycle, from design and documentation, to test and deployment.
The Web Application Description Language (WADL) is a machine-readable XML description of HTTP-based web services.

11. RESTful API at glance www.ebi.ac.uk/ebisearch/swagger.ebi
Example 1, 2 and 3
Example 4

12. Swagger interface: documentation
Each API method is documented in detail
Summary about a method
URL to call
List of parameters and HTTP headers
Response content type
Response messages
Sample Web Services clients of the RESTful API
Python
Perl
Java

13. Swagger interface: interactive testing
...

14. How to use the EBI Search RESTful API Example 1: get domain metadata

15. Example 1: info on a specific domain
Goal: get the metadata about the data domain OMIM (omim.org).
Domain search method:
/ws/rest/{domain}
Resource:
domain  omim
Parameters / headers:
None to set
OMIM: Online Mendelian Inheritance in Man - An Online Catalog of Human Genes and Genetic Disorders.

16. Example 1: execute the request
/ws/rest/omim
yutyutyuyt

17. Example 1: response /ws/rest/omim The response contains:
summary about the data domain
fields: searchable, retrievable, sortable
cross-references
facets
Curl URL can be used in a command line
Request URL can be copied and pasted in a browser
Facets are properties present in the data with different values.
Faceted search, also called faceted navigation or faceted browsing, is a technique for accessing information organised according to a faceted classification system, allowing users to explore a collection of information by applying multiple filters.

18. Example 1: domain info on the web interface
The EBI Search web interface can help in using EBI Search RESTful API.

19. How to use the EBI Search RESTful API Example 2: search and retrieve

20. Example 2: search on a specific domain
Goal: search and retrieve the OMIM identifier for the disease ‘amyotrophic lateral sclerosis 1’.
Domain search method:
/ws/rest/{domain}
Resource:
domain  omim
Parameters / headers:
query  amyotrophic lateral sclerosis 1
fields to retrieve  id, title
response content type  application/json

21. Example 2: execute the search query
/ws/rest/omim?query=amyotrophic lateral sclerosis 1&fields=id,title
yutyutyuyt

22. Example 2: response Number of search results OMIM id 105400
lateral sclerosis 1&fields=id,title
Number of search results
OMIM id

23. Example 2: custom HTTP headers
‘X-EBI-Search’ HTTP headers provide additional info

24. How to use the EBI Search RESTful API Example 3: search with facets

25. Example 3: search on a specific domain
Goal: get a list of entries in UniProt with an OMIM cross- reference to ‘amyotrophic lateral sclerosis 1’ (MIM ).
Domain search method:
/ws/rest/{domain}
Resource:
domain  uniprot
Parameters / headers:
query  MIM:105400
facetfields  chromosome
facetcount 10
format  json
More information about the query syntax can be found on EBI Search documentation page (

26. Example 3: execute the search query
/ws/rest/uniprot?query=MIM:105400&facetfields=chromosom e&facetcount=10&format=json
yutyutyuyt

27. Example 3: response
0&facetfields=chromosome&facetcount=10&format=json
...

28. Example 3: results on the web interface

29. Example 3: different output format
/ws/rest/uniprot?query=MIM:105400&format=idlist
A list of ids can be used as input to other bioinformatics tools
curl -X GET --header 'Accept: text/plain' \ '
DCTN1_HUMAN
SODC_HUMAN
FGGY_HUMAN
NFH_HUMAN
Various bioinformatics tools can take as input search results from EBI Search:
- Sequence similarity search tools (for instance BLAST, FASTA)
- Multiple sequence alignment (for instance Clustal Omega)

30. How to use the EBI Search RESTful API Example 4: get cross-references

31. Example 4: get list of cross-references
Goal: get UniProt entries with a cross-reference to OMIM id — same goal as in Example 3.
Cross-reference search:
/ws/rest/{domain}/entry/{entryids}/xref/{targetdomainid}
Resource:
domain  omim
Parameters / headers:
entryids 
targetdomainid  uniprot
facetfields  chromosome
facetcount 10
format  json
The same goal can be achieved in different ways using the EBI Search RESTful API.

32. Example 4: execute the xref request
/ws/rest/omim/entry/105400/xref/uniprot?facetfields=chromosome &facetcount=10&format=json
yutyutyuyt

33. Example 4: response
?facetfields=chromosome&facetcount=10&format=json
...
yutyutyuyt

34. Help and support

35. Help and support EBI Search RESTful API
EBI Search main documentation page
EBI Search support form
EMBL-EBI Web Services documentation
Webinars on programmatic access to EMBL-EBI resources and tools
take-rest-manual-searches
Thank you for watching this EMBL-EBI webinar.
The slides will be available in the on-line material for this webinar.

36. Upcoming webinars Feedback See the full list of upcoming webinars at
Feedback
Tell us what you think