Skip to content
Branch: master
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
extensions update all geojson schema refs May 2, 2019
openapi
README.md Updated readme May 2, 2019
STAC-extensions.yaml Merge branch 'dev' into api-spec-fix May 2, 2019
STAC.yaml Merge branch 'dev' into api-spec-fix May 2, 2019
api-spec.md Minor improvements that takes extensions better into account. May 2, 2019
examples.md expand API examples Apr 26, 2019
package-lock.json Updated dependencies to solve vulnerabilities and fixed URL to STAC h… Apr 29, 2019
package.json Renamed STAC+extensions.yaml to STAC-extensions.yaml May 2, 2019

README.md

STAC API

A STAC API is the dynamic version of a SpatioTemporal Asset Catalog. It returns STAC Catalogs, Collections, or Items, depending on the endpoint. Catalogs and Collections are JSON, while Items are GeoJSON - Features when just a single Item, or a Feature Collection when multiple Items are returned from a search.

The API is a Web Feature Service 3.0 (WFS 3) API, in that WFS 3 defines many of the endpoints that STAC uses. A STAC API should be compatible and usable with WFS3 clients. However, WFS 3 is still under development and while STAC tries to stay in sync with WFS3 developments, there may be discrepencies prior to final versions of both specifications.

In this directory

The Specification: The main description of the STAC API specification is in the api-spec.md file. It includes an overview and in depth explanation of the REST endpoints and parameters.

Extensions: API Extensions are given in the extensions folder. YAML fragments are provided for each extension with details provided in the README.

Examples: For samples of how the STAC API can be queried, see the examples.md file.

API Definitions: The API is described by the OpenAPI documents in the openapi folder.

OpenAPI definitions

The definitive specification for STAC API is provided as an OpenAPI 3.0 specification that is contained within several YAML files in the openapi and extensions directories.

These are built into the definitive core API specification at STAC.yaml, which can be viewed online at stacspec.org/STAC-api.html. An additional OpenAPI definition is provided at STAC-extensions.yaml that includes all the optional extensions, and can be browsed online at stacspec.org/STAC-ext-api.html.

In the openapi directory there are three files

  • WFS3.yaml - The WFS3.yaml file is the WFS3 OpenAPI definition as currently used by STAC
  • STAC.yaml - Contains additional endpoints and components that STAC uses, which is treated as a WFS 3 extension
  • STAC.merge.yaml - A file referencing the above two used to create the final STAC.yaml definition

A basic STAC implementation implements both the WFS3 and STAC definitions.

The YAML files in the extensions folder are fragments. Fragments are used to describe incomplete pieces of an OpenAPI document, and must be merged with a complete OpenAPI document to be usable. This way extensions can be kept separate, and implementors can combine just the extensions they want to use in order to create a custom OpenAPI document they can use.

Editing should be done on the files in the openapi and extensions directories, not the STAC.yaml and STAC-extensions.yaml files, as these are automatically generated. If any of the files are edited, update the OpenAPI docs to overwrite the files:

$ npm install
$ npm run generate-all

Create your own OpenAPI document by combinining the STAC definition with the extensions you want by creating a myapi.merge.yaml file. This file should contain a line indicating the files that need to be merged:

!!files_merge_append ["STAC.yaml", "extensions/query.fragment.yaml"]

Then, run the yaml-files command line tool:

$ npm install
$ yaml-files myapi.merge.yaml myapi.yaml

API Evolution

The STAC API is still a work in progress. It currently tries to adhere to the WFS 3 API specification, with some STAC specific extensions, but WFS3 is also evolving and not finalized. The WFS 3 portion of the API is provided in the WFS3.yaml and represents the version of WFS 3 that is currently being used by STAC. It may diverge some with the WFS3 spec at any given time, either out of date or 'ahead', with proposals to align WFS3. The long term goal is for STAC's API and WFS 3 to completely align, ideally all of STAC API is made from WFS 3 plus its extension ecosystem, and STAC just focuses on the content. But until then STAC will work to bring practical implementation experience to WFS 3.

The evolution of the STAC Item spec will take place in this repository, primarily informed by the real world implementations that people create. The goal is for the core API spec to remain quite small and stable, with most all the evolution taking place in extensions. Once there is a critical mass of implementations utilizing different extensions the core API spec will lock down to a 1.0.

You can’t perform that action at this time.