Skip to content

Latest commit

 

History

History
42 lines (24 loc) · 3.09 KB

REST.md

File metadata and controls

42 lines (24 loc) · 3.09 KB

REST API documentation

Brief explanation

The Ensembl REST APIs provide language-agnostic programmatic access to genomic data. The existing endpoints have been added piecemeal over time, and as such there exists redundancy of endpoints and inconsistency between the ways the endpoints have been implemented. We are in the process of auditing the endpoints to improve this, and would like to take the opportunity to improve our documentation with it.

The REST API’s documentation is split between an auto-generated description of our endpoints (https://rest.ensembl.org) and a wiki user guide (https://github.com/Ensembl/ensembl-rest/wiki).

Our auto-generated endpoint description uses an in-house custom system and is in need of updating and modernising.

Our user guide was first written over five years ago and is due for review to ensure it continues to be informative and relevant to users.

During this project, we would hope a prospective candidate would investigate alternatives to our in-house systems and begin to replace them alongside working with our engineers to produce an improved user guide/manual.

Expected results

  • Evaluation and selection of suitable technology for documenting the REST API endpoints
  • Trialing selected technologies on a subset of endpoints and then rolling it out to other endpoints
  • A new user guide/manual

Commitment

Part-time

Mentors

  • Astrid Gall is an Ensembl Outreach Officer. She creates online help and documentation pages as well as training materials, delivers training workshops, answers help emails and manages social media -- anything that involves interacting with people who use Ensembl and helping them along. Her role in this project will be to help define the user's needs for documentation and also to explain the content where necessary.

  • Beth Flint is the Ensembl Applications Project Leader. The Applications team develop a variety of systems which are either partially or wholly RESTful APIs. Her role in this project will be to provide technical information and define the needs of the developers in finding a solution that is maintainable and sustainable.

Sample task

Anyone interested in the project should complete this short task and send a report on it.

The current documentation for the Ensembl REST API is available here.

  1. Do you see any weaknesses or strengths in this document in its current form?
  2. If you have identified any weaknesses, which would be the most important to address and why? Provide a brief plan (bullet points are fine) of how you would go about addressing them.
  1. Many websites and organisations provide RESTful APIs to allow developers to interact with their services. Identify and provide links to three APIs that you believe are well documented and briefly describe why you think each is successful.

More info

If you want to learn more about the Ensembl REST API, have a look at our up-to-date online course (https://www.ebi.ac.uk/training/online/course/ensembl-rest-api). It includes interactive Jupyter notebooks in Python, Perl and R (https://notebooks.azure.com/ensembl-training).