JAL-3851 api_specification.md in progress

diff --git a/doc/api_specification.md b/doc/api_specification.md
new file mode 100644 (file)
index 0000000..8ec1baa
--- /dev/null
+++ b/doc/api_specification.md
@@ -0,0 +1,40 @@
+# Jalview Rest(-like) API
+
+## Launch Jalview with API active on specified port
+
+`java -jar jalview_all.jar -nosplash -nowebservicediscovery -startapi -serverport 2021`
+(-nosplash and -nowebservicediscovery just to save time/output)
+
+## Open a MSA window with existing data
+
+`*POST* http://localhost:2021/jalview/api/inputalignment`
+with body of HTTP request being content of file (automatic parsing by Jalview)
+
+`*GET* http://localhost:2021/jalview/api/inputalignment?data=<data>`
+with <data> being content of file (limited size)
+
+`*GET* http://localhost:2021/jalview/api/inputalignment?file=<fileURI>`
+with <fileURI> being a file
+
+`*GET* http://localhost:2021/jalview/api/inputalignment?url=<URL>`
+with <URL> being a URL to a file
+
+## Open a MSA window with online resource fetch
+
+`http://localhost:2021/jalview/api/fetchsequences/<resource name>/<sequence ids>`
+<resource name> is one of "ensemble", "pdb", "ensembl-tr", "ensembl-gn", ["uniprotkb/swiss-prot", "uniprotkb/trembl", ""uniprot/sptrembl", "uniprot/swissprot" not yet implemented]
+<sequence ids> ids for fetch
+
+### optional parameters
+`id=<your specified id for this request>`
+
+### Returns (as key=value pairs in the body of the response)
+```
+id=<the given id for this request>
+status=<STARTED|IN_PROGRESS|FINISHED|ERROR|NOT_RUN>
+
+
+
+
+
+