Skip to content

RiskLib 0.3 API

Jump to bottom Edit New page
bwyss edited this page Mar 16, 2011 · 3 revisions

In order to build a robust ecosystem of applications, community partners, and mashups against OpenQuake we need to provide a robust RESTful API.

Notes

  • Assumptions

    • The GEM Foundation and governing board members want a robust ecosystem of applications and mashups against the OpenQuake platform.
    • Assumption Y

  • Design

The OpenQuake platform should have a public API by the June 2011 release. The sooner we can hash out the API features, and its implementation the better, as we can provide a developer preview between the Jan 2011 0.2 release and the release of 0.3 in June.

For simplicity and because it supports proper mapping of HTTP resources to application resources, the API will be RESTful. All actions taken against OpenQuake's API will be a series of verbs against the exposed resource nouns, (e.g. GET /OpenQuake/api/version/some_resource.xml instead of: /OpenQuake/api/version/get_some_resource?format=xml). This is cleaner, easier to understand, and is the preferred API style for the larger internet community interested in Mashups.

At minimum, the mvp of the API must support the following data formats: raw XML, NRML, and JSON. If community interest justifies, we should also support WMS/WFS with the understanding that WMS/WFS support should only been in OpenQuake for only a few releases (it should be deprecated for more web friendly formats, and should only be included to ensure compatibility with GeoServer and GeoEditor).

The API must be versioned, and to ensure stability of the application/mashup ecosystem, should only be updated in ways that break existing functionality once per year. Adding additional resources to the API is fine mid-cycle, so long as they obey existing resource semantics and do not interfere with the functionality of existing resources.

For the first version of the OpenQuake API, we will expose the following resources:

  • Vulnerability

    • Model
      • GET /api/version/vulnerability/models.format -> Returns a list of available vulnerability models.
      • GET /api/version/vulnerability/model/id.format -> Returns a vulnerability model in the chosen format.
      • POST /api/version/vulnerability/model.format -> A user provided vulnerability model is saved, returns a reference to the created object as: vulnerability/model/id.format.

  • Regions

    • Region
      • GET /api/version/regions.format -> Returns a list of available regions.
      • GET /api/version/region/id.format -> Returns a region in the chosen format.
      • POST /api/version/region.format -> A user provided region is saved, returns a reference to the created object as region/id.format.

  • Exposure

    • Exposure
      • GET /api/version/exposures.format -> Returns a list of available exposures.
      • GET /api/version/exposure/id.format -> Returns a exposure in the chosen format.
      • POST /api/version/exposure.format -> A user provided exposure is saved, returns a reference to the created object as exposure/id.format.

  • Hazard

    • Hazard Curve

      • GET /api/version/hazard/curves.format -> Returns a list of available hazard curves.
      • GET /api/version/hazard/curve/id.format -> Returns an already calculated hazard curve for a block of sites.
      • POST /api/version/hazard/curve.format -> Calculates a GMF for a block of sites and returns a list of created GMF resources as: hazard/curve/id.format

    • Mean Ground Motion Fields

      • GET /api/version/hazard/mgm_fields.xml -> Returns a list of available MGM fields
      • GET /api/version/hazard/mgm_field/id.format -> Returns an already calculated mean ground motion field for a block of sites.
      • POST /api/version/hazard/curve/mgm_field.format -> Calculates MGM for a block of sites and returns a list of MGM resources as: mean_ground_motion/id.format.

  • Risk

    • Compute Risk
      • GET /api/version/risks.format -> Returns list of available risks.
      • GET /api/version/risk/id.format -> Returns a calculated risk for a block of sites.
      • POST /api/version/risk.format -> Calculates the risk for a block of sites, this will require a reference to a Hazard Curve resource in addition to the passed sites.

A later release of the API (perhaps in the same 2011.x series of API version) should support these additional resources:

  • HazardModel
    • GET /api/version/hazard_models.format -> Returns a list of hazard models supported by the OpenQuake/OpenRisk engine.
    • GET /api/version/hazard_model/id.format -> Returns configuration data for that hazard model, for use in POST /api/version/hazard.format
  • RiskModel
    • GET /api/version/risk_models.format -> Returns a list of risk models supported by the OpenQuake/OpenRisk engine.
    • GET /api/version/risk_model/id.format -> Returns configuration data for that risk model, for use in POST /api/version/risk.format

When any of the POST actions are performed an OpenQuake Job will need to be created, since OpenQuake jobs are asynchronous the API will either need to use long-polling to provide the appearance of synchronous behavior, or will need to support the attachment of a callback URL to which the OpenQuake API can write.

  • User stories:

  • Suggested Implementation:

It would be easiest to create the API as a WSGI framework, because it makes it very easy to hang middleware off the chain (making things like authentication absolutely trivial). A good place to look would be the OpenStack Nova API which was turned into a WSGI framework for the Austin release.

Back to Blueprints

Add a custom footer
Add a custom sidebar
Clone this wiki locally