PEML Live! REST API

There are currently two approaches to incorporating PEML into tools that wish to process PEML descriptions. You can either use a library to directly embed PEML support into your application, or you can use our web micro-service through an open REST API.

Using the PEML Library as a Ruby Gem

Currently, the only parser library for PEML is written in Ruby, although other programming language implementations are welcome as contributions.

Installing and using the PEML Ruby gem

Using the REST API

If no library is available for your preferred programming language, or if you would prefer to use an external micro-service instead of embedding a PEML library in your application, this site hosts a PEML parsing micro-service that provides complete access to all of the options of the native library parsing implementation.

For the programmatic REST API, there is only one entry point at:

https://endeavour.cs.vt.edu/peml-live/api/parse

View the Swagger documentation for this API

This API entry point accepts either GET or POST requests with parameters.

peml (string or file)
The PEML content to be parsed. This is the only required parameter. It can be either a plain string (good for interactive GET exploration) or a multi-part form file parameter (better for programmatic POST requests).

result_only (boolean)
Indicate whether to return just the parse result (true), or (the default) a hash of the form { value: <parse_result>, diagnostics: [<messages>] }.

interpolate (boolean) not yet implemented
Indicate whether or not to interpolate variables embedded in PEML field values.

render_to_html (boolean) not yet implemented
Indicate whether PEML fields containing markdown/markup values should be rendered to HTML in the result.

inline (boolean) not yet implemented
Indicate whether to inline field contents in the PEML description when the value is specified as a URL.

format (string)
This parameter indicates the format requested for the response, which is one of (json, yaml, xml). This can be specified as an explicit parameter named "format" passed in the request, or can be specified directly in the request URL as a file name extension (e.g., requesting from https://endeavour.cs.vt.edu/peml-live/api/parse.yaml?...). If not explicitly provided, it will be inferred through the "Accept:" headers provided in the request, or defaults to json if not specified anywhere else. See the grape gem's discussion of API formats for more details about how the format of the response is determined.