Lightning

I assume http://lightning-dev4.curoverse.com/pad/p/lightning-api is the most up to date and the one I should primarily be looking at.

All API requests should have an example associated with them: GET /tiles/{version-int}, GET /tiles/{version-int}/{path-int}, GET /tiles/{version-int}/{path-int}/{step-int}, GET /callsets/{callset-name}/gvcf, GET /callsets/{callset-name}/vcf, POST /callsets/filter-phase-insensitive, POST /callsets/filter-phase-sensitive.

A short description of non-intuitive return parameters should be given. For example, POST /tile-variants/loci has as it's return value [['hg19','chr1',0,300,3248]]. I would add a note here with something like "returned is reference locus for 'hg19' on chromosome 1, 0 indexed (as specified by the third return value), starting at 3000 and ending at 3248 (exclusive). See the "Locus" section above for more details". In general, making each description of the API functions as self contained as possible is better.

What does "acts like a POST" mean? Please explain in the document.

Otherwise seems like a good initial attempt at a Lightning API.

Unfortunately, the link you provide is the Lightning API attempt we designed last march and the one I used as inspiration for the current API. The most recent API specs are in https://github.com/curoverse/lightning/ under the 'docs' directory.

As requested, I'm focusing on the "Data Structures ..." and the "Lightning API.." sections.

Some points:

• All API queries should have an example including the request example. I notice a lot of responses but few have requests. Even if it's obvious it still should be provided to provide some context.
• I don't know what POST /callsets is doing. If this is future functionality maybe it should be taken out of this spec. If you want to keep it please document what it's doing, what each of the parameters means and what the behavior is.
• Searches can be specified and queried without any credential information? Doesn't this pose security risks? Won't searches accumulate? Why have this in the first place?
• Provide a detailed description of the response to 8.2.2 POST /tile-variants/loci describing what the vector ['hg19', 'chr1', 0, 3000, 3248] represents. A brief "third parameter is the index (0 in this case), start position, end position (non-inclusive)".
• Provide examples for each of the data types in the Data Structures Specifications section.
• What is the tag-set-integer from GET /tile-library/tag-sets/{tag-set-identifier} (section 8.1.4)? Give a brief explanation.
• In section 8.1.5, make it clear that the "BRCA Lightning Instance" is a Lightning server only serving those two tile paths and nothing else.
• What is the num-positions in 8.1.6? Explain briefly what that number represents.

Maybe premature for this document but having concrete examples (via a 'wget', 'curl' or some other facility) helps with understanding. In general, having each section or sub-section be as self contained as possible is something I would strive for. The way I read API documents is as a reference, often jumping to the section that I want to understand. Usually, an example is good enough for me to understand what it does and how to use it. I consider it undesirable to bounce around in the document looking up definitions or terminology so that I can understand what a particular API call does.

I also think we should hold off on providing facilities to create objects via the API. I'm happy to hear otherwise but this has some implications that we might not want to address right now.

Otherwise it looks good as an initial API.