Smoke Server API
The Smoke Server API is basically the specification of the URLs for a Smoke
server. I.e.:
- What does http://www.foo.com/smoke/ yield?
- What does http://www.foo.com/smoke/projects/ActivePython/
yields?
- What URL query and fragment parameters are valid for any of the
Smoke URLs.
I suppose you could call this a site map or URL map for a Smoke server.
Note: The Server API is still under development. If you have suggestions or
any feedback please ping TrentM@ActiveState.com and/or
DavidA@ActiveState.com.
A Smoke URL is defined to have these pieces:
smokeroot/smokepath;parameters?query#fragment
where,
- smokeroot
- is the URL to a Smoke server CGI driver.
- smokepath
- is the URL subpath from the base path to which the Smoke Web CGI
driver is mapped.
- parameters (optional)
- are new to me! I have never seen this in a URL.
- query (optional)
- is the URL query string.
- fragment (optional)
- is the URL fragment string.
for example, if the root of a smoke server (aka smokeroot) is
http://www.foo.com/smoke/ then:
| URL |
smokepath |
|---|
| http://www.foo.com/smoke/ |
/
|
| http://www.foo.com/smoke/builds/ |
/builds/ |
and if the root of a smoke server (aka smokeroot) is
http://smoke.foo.com/ then:
| URL |
smokepath |
|---|
| http://smoke.foo.com/ |
/
|
| http://smoke.foo.com/builds/ |
/builds/ |
A Smoke server site map has two main purposes:
- Provide URL forms so Smoke clients can submit data to the Smoke
database via HTTP.
- Provide a user-friendly URL API for querying and visualize the data in
the Smoke database. (If I knew anything about it I would probably be
talking about REST right now.)
The Questions section below proposes a number of questions that a good
Smoke/Tinderbox-like system should easily answer for a user.
Here is a proposed high-level URL map for a Smoke site. More detail will be
given for each branch below.
| smoke URL |
Description |
|---|
/
|
Introduces this Smoke database/site and provides
useful/common links to subpaths. |
| /client/... |
Forms providing an HTTP transport for calling the
Smoke Client API to add data. |
| /admin/... |
Administrative branch for configuring and getting
info of database status. |
| /builds/ |
Provide a build summary for all projects for
which there is build data. |
| /builds/project |
Provide a full build table for the given
project. |
| /builds/project/latest |
Provide information on the latest finished build for
the specified project |
| /build/ |
Provide a summary page showing some data about
recent (or perhaps "significant") builds with a
form for finding a specific build. |
| /build/buildid |
Provide a full description of the given
buildid, including build success/failure,
summary of regression and performance tests,
and log. |
| /perf/perfid |
A historical analysis of the specified performance
test, up to and including the test specified
(note that a perfid refers to a particular
performance test result). |
| /perfdesc/perfdescid |
Description of a particular performance test,
which is identified by a name and a project name. |
| /test/testid |
A historical analysis of the specified regression
test, up to and including the test specified
(note that a testid refers to a particular
regression test result). |
| /machines/ |
A listing of machines that have provided data for
this Smoke site. |
| /machine/machineid |
Detailed information about the specified machine |
Other ideas:
Project-specific pages, e.g. to allow a quick one-page summary of
build status, recent and relevant test results and some important
performance metrics.
Shorter URLs to get to say, the builds page for ActivePython. It might
be nicer to visit:
http://smoke.activestate.com/ActivePython
rather than the currently suggested:
http://smoke.activestate.com/builds/ActivePython
or even this might be nicer:
http://smoke.activestate.com/ActivePython/builds
This is a list of questions that it is intended that a running Smoke database
be able to easily answer for a user.
- What is the state of builds for project X?
Answer: Look at: /builds/X
- Are these builds being tested and have those tests all passed?
Answer: Look at /builds/X/latest
- Why did this build pass or fail? I.e. project a link to log output.
- Are there any performance measurements for this build? for this project?
- Is there a build in progess?
- To what source state does this build correspond?
There is a single .../client/method "page" for each Client API method.
Each such page provides a web form interface to that API method. As well, the
same form can be driven by a Smoke client automatically. This is aided by
providing an "Interface Type" form parameter it whose value can be set to
script to have the Client API method page return results and errors
encoded at test/plain for simpler parsing.
TODO: Should add more details.
This branch will provide the ability to configure and view the status of the
running Smoke server. Its pages should also allow the use of the it form
parameter (see above) for Smoke client usage.
