Grimoire 0.4 API proposal

gistfile1.md

HTTP API

While Grimoire 0.3.X lacked a API for searching the backing datastore, Grimoire 0.4.0 resolves that limitation adding a HTTP API with JSON or EDN responses.

As of the writing of this document, the HTTP API is at version v0.

All routes return an object, representing either success or failure.

In JSON:

{"result": "success",
 "body":   ...}

{"result": "failure",
 "body":   ...}

In EDN:

{:result :success,
 :body   ...}

{:result :failure
 :body   ...}

The exact content of each body is documented below. Note that a full client for this API is provided as part of lib-grimoire.

/api/v0?op=groups

Succeeds returning a list of records representing the various groups known to Grimoire.

In JSON:

{"result": "success",
 "body"  : [{"name":     "/org.clojure",
             "html":     "/store/org.clojure",
             "children": {"notes":     "/api/v0/org.clojure?op=notes",
			              "meta":      "/api/v0/org.clojure?op=meta",
                          "artifacts": "/api/v0/org.clojure?op=artifacts"}},
             ...]}

/api/v0/$GROUP?op=notes

Succeeds returning a simple string, being markdown formatted but unrendered notes about the group in question.

Fails only if there is no such $GROUP. A group with no notes will succeed with the empty string as its result.

In JSON:

{"result": "success",
 "body"  : "some notes"}

Note that ?op=notes is defined over every path in this API except for the base path, so further mention of it is elided.

/api/v0/$GROUP?op=meta

Succeeds returning a map, being the metadata known about the group in question, or the empty map if nothing is known.

While this structure has no mandatory keys, the following are cannonical values:

• "url"

Fails only if there is no such $GROUP. A group with no notes will succeed with the empty string as its result.

Note that ?op=meta is defined over every path in this API except the base path, so further mentions of it are elided pending documentation of the metadata which may be expected from different resources.

/api/v0/$GROUP?op=artifacts

Succeeds returning a list of records representing the various artifacts in a known group.

Fails only if there is no such $GROUP. An empty group will succeed returning an empty body.

In JSON:

{"result": "success",
 "body"  : [{"name":     "/org.clojure/clojure",
             "html":     "/store/org.clojure/clojure",
             "children": {"notes":    "/api/v0/org.clojure/clojure?op=notes",
 						  "meta":     "/api/v0/org.clojure/clojure?op=meta",
                          "versions": "/api/v0/org.clojure/clojure?op=versions"}},
             ...]}

/api/v0/$GROUP/$ARTIFACT?op=versions

Succeeds returning a list of records representing the known versions of a the artifact in question.

Fails only if there is no such artifact or group.

In JSON:

{"result": "success",
 "body"  : [{"name":     "/org.clojure/clojure/1.6.0",
             "html":     "/store/org.clojure/clojure/1.6.0",
             "children": {"notes":      "/api/v0/org.clojure/clojure/1.6.0?op=notes",
 						  "meta":       "/api/v0/org.clojure/clojure/1.6.0?op=meta",
                          "namespaces": "/api/v0/org.clojure/clojure/1.6.0?op=namespaces"}},
             ...]}

/api/v0/$GROUP/$ARTIFACT/$VERSION?op=namespaces

Succeeds returning a list of records representing the namespaces in the given version.

Fails if the version, artifact or group does not exist.

In JSON:

{"result": "success",
 "body"  : [{"name":     "/org.clojure/clojure/1.6.0/clojure.core",
             "html":     "/store/org.clojure/clojure/1.6.0/clojure.core",
             "children": {"notes":    "/api/v0/org.clojure/clojure/1.6.0/clojure.core?op=notes",
 						  "meta":     "/api/v0/org.clojure/clojure/1.6.0/clojure.core?op=meta",
                          "macros":   "/api/v0/org.clojure/clojure/1.6.0/clojure.core?op=macros",
                          "vars":     "/api/v0/org.clojure/clojure/1.6.0/clojure.core?op=vars",
                          "fns":      "/api/v0/org.clojure/clojure/1.6.0/clojure.core?op=fns",
						  "specials": "/api/v0/org.clojure/clojure/1.6.0/clojure.core?op=specials",
						  "sentinels":"/api/v0/org.clojure/clojure/1.6.0/clojure.core?op=sentinels"}},
             ...]}

/api/v0/$GROUP/$ARTIFACT/$VERSION/$NS?op=all

Succeeds returning a list of records representing all the defs and sentinels in the given namespace.

Fails if the namespace, version, artifact or group does not exist.

In JSON:

{"result": "success",
 "body"  : [{"name":     "/org.clojure/clojure/1.6.0/clojure.core/concat",
             "html":     "/store/org.clojure/clojure/1.6.0/clojure.core/concat",
             "children": {"notes":    "/api/v0/org.clojure/clojure/1.6.0/clojure.core/concat?op=notes",
 						  "meta":     "/api/v0/org.clojure/clojure/1.6.0/clojure.core/concat?op=meta",
                          "examples": "/api/v0/org.clojure/clojure/1.6.0/clojure.core/concat?op=examples"}},
             ...]}

The ops, macros, vars, fns, specials and sentinels are simply type selectors which return distinct subsets of these results.

/api/v0/$GROUP/$ARTIFACT/$VERSION/$NS/$SYMBOL?op=examples

Succeeds returning a list of examples for this version of the symbol as strings of plain text. Note that this does not return all examples for all prior versions.