opengeospatial/ogc-web-api-guidelines

ogc-web-api-guidelines's Issues

Principle #7 – Error Handling

• Error Codes are the developers insight into your API
– So be precise and as detailed as possible
• Usually, errors are associated with HTTP status codes
• But, support a „switch off“ which always returns a status code 200 plus additional information in the response body
– e.g. ?suppress_response_codes=true
• Return detailed human readable error no. + description + information how to fix things + contact details
{ “developer_message”: “…“,
„user_message“: „...“,
„error_code“: „...“,
„contact_details“: „...“
}

Metadata - Guideline 13

This guideline calls for metadata to be a part of the resource tree (a path element). In practice, we are associating metadata with resources though an association. Most notable, the service-meta and data-meta association types. This is a more flexible, and arguably more intuitive approach than that prescribed in Guideline 13.

Principle #5 – Don’t mix Singular and Plural

• It doesn’t matter if you use Singular or Plural for your nouns to build the path. But, don’t mix!
• Use concrete names to build the path
• /v1//
• kinds using plural := {features, maps, tiles, coverages, observations, processes, facts, ...}
• kinds using singular := {feature, map, tile, coverage, observation, process, fact, …}
• E.g. using plural
– POST /v1/features/tiger_roads/
– PUT /v1/maps/green_spaces/area51
– GET /v1/tiles/water_ways/4326/0/0

Principle #3a - Use Well-Known Resource Classes

An additional principle from the Testbed 12 REST User Guide

Change reference to Web Feature Service 3.0 to something more modern

idem

Principle #11 – Partial Responses

• Allow the developer to fetch just not all the detail of a resource but select the fields of interest
• How to design the API to support this?
• Option 1: Integrate into path
– /v1/features/highways/A8:(name, geometry)
• Option 2: Use comma separated list as query parameter e.g. fields
– /v1/features/highways/A8?fields=name,geometry
• Advantage of option 2: It can be combined with other search options
– /v1/features/highways?id=A8&fields=name,geometry

"OGC Web API" is misleading

The idea should be to specify OGC API elements or building blocks that can be used in APIs, not to define a "OGC Web API".

common design principles in main-stream IT

There are common design principles in main-stream IT that should be adopted to ease the adoption of OGC Web APIs.

An informative list of sites/documents/... that describe some of those common design principles in main-stream IT would be useful.

Principle #3b – Keep the Base URL Simple

• Never release an API without versioning
• Use a version string as the most left of your path
– /v1 (don’t you dot notation)
• Add the kind of resource to the path
– /v1/{features, maps, tiles, coverages, processes}
• Use nouns not verbs to build the path
– /v1/features/highway or /v1/maps/topo25 etc.
• Use two base URLs per resource kind
• Use HTTP methods as verbs
– GET /v1/features/highway or /v1/features/highway/A8

Register geospatial relation types in the IANA register

see Linda's comment in #23

Principle #8 – HTTP Status Codes

• More then 70 HTTP status codes exist (summary in RFC 7231)
• You should reduce to the most important once
• Option Set #1 – Basic set Option Set #2 – Additional
– 200 – OK – 201 – Created
------------ – 304 – Not Modified
– 400 – Bad Request – 401 – Unauthorized
------------ – 403 – Forbidden
------------ – 404 – Not Found
------------ – 405 – Method Not Allowed
------------ – 409 – Conflict
------------ – 410 – Gone
------------ – 412 – Precondition Failed
– 500 – Internal Server Error – 503 – Service Unavailable

Principle #15 – Miscellaneous

• Describe the API in OpenAPI has value to the developer

Example checklists

An example API Guidelines developed for API-Common - Core has been posted to the examples folder. Feel free to re-use this example for your own standard, and post the results to this repository.

Ensure discover resources mechanism.

In you API, is it possible to the "follow the links" approach and discover all the resources (this is how the web works). The second possibility is provide a way to enumerate resources based on URI templates (e.g, \collections will enumerate the collectionId's in as a response).

It is a good practice to provide enumerations but there are some cases where only a lower and upper limit for an incremental consecutive number is fine, like in WMTS URL templates.

In any case the client should be able to figure our all the resource url's by finding them explicitly, asking for them or knowing a rule to generate them.

Is it worth to have a principle for a good API?

Reorganize Principles 7 and 8

Principle #7 – Make Responses Clear

Use HTTP Status Codes from RFC7231 to indicate the results of the request. Since more than 70 status codes exist, reduce the use in your API to the most important ones. For example:

TABLE

Response documents should reflect the status codes. 4XX responses indicate that the client is in error so the response should indicate what is wrong with the request. 5XX responses indicate that the server is in error so the response should include contact information. Since debugging information for server problems is not actionable by the client, it should be logged and not returned in the response document.

Principle 8 goes away. See #38 for a candidate replacement.

Rewrite Principle #17 (geospatial relations -> geospatial elements)

Principle #17 – Follow OGC Guidelines regarding geospatial elements

• Provide SRSs with all coordinates.
• Where possible, explicitly name coordinates instead of relying on coordinate order. When this is not possible, follow the OGC Axis Order Policy.
• When needed, use WKT2 to describe SRSs. (from #37)
• Use explicit geospatial relations. (as in the existing Principle 17)

Replace felxible -> flexible

In the title of principle 10: Allow felxible Content Negotiation

Principle #14 – Security

• Host your API on HTTPS
• Require OAuth2 Bearer Tokens to control access
• Use OpenID Connect to fetch use claims

Non-functional links in README

The links to the latest published version near the top of the README go nowhere. The links should be updated or removed.

Principle #2 – Keep It Simple and Intuitive

• Who are you targeting?
• What are you trying to achieve?
• Make the developer of the API successful as quickly as possible!
• Don’t forget to build in security from the start!

Principle #6 – Put Complexity behind the ‘?’

• This where the fun begins
• query-string parameters should be used to select a resource(s) based on the(ir) characteristics
– /v1/features/highways?id=A8 => returns highway A8
– /v1/features/highways?id=A8,A9 => returns highways A8 and A9
• But what if you select on a resource instance?
– /v1/features/highways/A8?id=A8
should that return true or the resource?
– /v1/features/highways/A8?id=A81
should that return false or null?
• Use of the query string to select resources is highly domain specific and must be described on a case to case basis

Great APIs are testable

We are developing the compliance test framework for REST/OpenAPI services. This framework has to make some assumptions about how a service is structured. These assumptions will mature into conventions which all testable OGC REST/OAS services should comply with.

Pagination

• Use limit and offset as query string parameters is common sense
– e.g. /v1/features/highways?limit=50&offset=100
• You must return metadata with each response providing the total number of resources available
– e.g. total
• As an alternative to application processing the response, you should try to use Web Linking (RFC 5988)
– Use HTTP Response Header to provide URLs for fetching the next / previous page
– This approach is application neutral and should be provided by the API as the default

Bulk operations

Please consider bulk operations on thousands of features at the same time (read, update, ...) pagination is not enough

Consolidate the SecureDimensions branch in the master. Focus on WebAPI or in RESTful resources?

I believe we need converge on a single document for the discussion in September. I believe there are significant contributions in the SecureDimensions branch that can be incorporated in the master.

The main difference I see is that the "master" is more focused on RESTful resources and the "SecureDimensions" branch more on WebAPI. I believe we need to avoid falling into REST and non-REST discussion again so I personally recommend to remove all reference to REST. This does not preclude that a good WebAPI should consider an analysis of the "resources" it considers and a clear separation between a requesting a resource and the response of the "filter" on a resource (that is not necessarily a resource but is a perfectly acceptable beast).

How can we get back to a single master branch by incorporating what is great from the "SecureDimensions" branch in the master that needs to be the "everybody's" branch?

Principle #13 – Metadata

• This part of the API helps the developer to understand what “the deal is with the resources”
• Use a clear and dedicated endpoint to provide metadata
– clearly different from the resource endpoints
• /v1/metadata or /v1/discover
• Starting with the next level, use URL path structures used for accessing resources
– /v1/metadata/features
– /v1/metadata/features/highways
– /v1/metadata/features/highways/A8
• Allow ‘?’ operator to send selection queries

Addition of HTTP status code 302 to Option Set 2 in Principle #8 - HTTP Status Codes

Should include HTTP status code 302 in Option Set #2.

302 is used by opengis.net to support persistence in URIs (through redirection).

Are all principles equal ?

At some future point you may want to rank or indicate the relative importance of different principles as some will have greater influence on design than others ?

Don’t Reinvent

• Aspects that are already solved in main-stream IT, simply adopt
• Just domain specific aspects – And that will be a lot…

Principle 17 - Use Well-Known URL Templates and Access Paths

An additional principle from the Testbed 12 Rest User Guide

OGC Web API Design Principles

This issue is for the general discussion of the OGC Design Principles

Description of OGC Architectural Philosophy

Purpose is to develop a section to modular Web API to make readers understand the context.

Reference to obsolete RFC 2616

The guidelines refer to RFC 2616, but that RFC has been obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235, see also https://www.rfc-editor.org/info/rfc2616 . The references to RFC 2616 should be replaced by the appropriate RFC from the aforementioned list. E.g. RFC 7231 for HTTP methods.

Principle 19 - Make use of geospatial relations

There is something about geospatial that make it intrinsically NOT related with hypertext: georeference and geospatial relations:
Given a coverage cell, there is always a cell immediately to the East, another immediately to the North, another immediately to the South, another immediately to the West. This is a geospatial relation. Geospatial relations are so abundant in a coverage that will be very very inefficient to explicitly state then in hypertext. Relations are embedded in the coverage model (some of them could be made a bit more explicit in URL templates, but it should not be necessary). A WCS client need to be aware or spatial relations. That is not REST (in the sense that they are not explicit in hypermedia but there is nothing we can do about. Actually, spatial relations are a good thing!!.

My proposal is adding that geospatial relations that are intrinsic to the model should not be made explicit as hypertext. A client should be aware of spacial relations on the data model. In some cases could make some of them explicit in a single URL template by following some patters such as the ones used in WMTS and tilerow and tilecol.

Resolve comments from Carl Reed

Carl submitted comments as red-lines to a Word version of the API Guidelines document. It can be found in the Comments folder.

Change requirements to recommendations

Change the requirements section to recommendations. Recommendations should be testable but not normative.

Plurals to return collections in Principle #5 – Don’t mix Singular and Plural

This principle should include the following “Use Plurals to return collections of resources and Singular to return a single instance”.

This was demonstrated to work well in Testbed-12. Have a look at the “Resources Summary” section of OGC 16-59 http://docs.opengeospatial.org/per/16-059.html#_resources_summary

Principle 17b - Use OGC services reserved URIs

Should we reserve some paths for some "Common" cases and special meanings?. Can this be and added principle?

For example:
/api
/conformance
/collections
/metadata

Define Default behavior if parameters are not there.

One rule that we are trying to use in defining APIs is that almost all parameters are optional and that there are default behavour for the lack of them

URIs and link references should be predictable

It should be deterministic what document is going to be returned when a URI is opened.

Principle #XX – Make documents predictable

Make the document type of all resources predictable so that there is no ambiguity in how the client is supposed to parse the document. This applies to resources accessible through both a URI pattern (see Principle #4) and through a link (see #38).

Principle #4 – Use CRUD

• Allow CRUD Create, Read, Update, Delete, and Execute
• Allow HTTP methods that operate on resources; GET, POST, PUT, DELETE
• Also support HTTP communications methods
– HEAD to return HTTP Headers with no payload
– OPTIONS to support CORS

Hard to identify what is meant to be normative or informative in the text

For each principle, clearly separate which text is the principle / "normative" and what is discussed / informative explanation.

Tiles are not always equally divided. Therefore, it is not always assigned to a simple matrix.

Equally divided tiling (regular tiling scheme) is treated like an implicit common sense in the geo community, but it seems to keep his eyes away from its issues. Especially in vector tiling, the issue is serious.

We have already faced issues of equally divided tiling practically over 10 years ago.
The problem is described in this slide *1.

For that reason, we implemented unequaled tiling *2 and have been practically used for many years, and have also done that standardization *3.
In OGC's Vector Tiling Report *4, 6.4.3., There is a slight mention on non-equal tiling, but ignored without exploring that problem. I sent comments on this to contact point, but I could not get a reasonable response.

I think that geo-community should face these issues of equal divided tiling soon.

• 1: Quad Tree Composite Tiling: https://www.slideshare.net/totipalmate/quad-tree-composite-tiling-in-english
• 2: SVGMap (Open Source Implementations) http://svgmap.org/
• 3: Japan Industrial Standard (JIS): X.7197: http://www.jisc.go.jp/policy/nenji/Japans_Standardization_Policy_2013.pdf
• 4: http://docs.opengeospatial.org/per/17-041.html

Principle #9 – Use of HTTP Header

• Used to provide information that does not change the logic of the API
– e.g. HTTP Authorization
• Keep in mind that not all JS-API support adding “stuff” into the HTTP request header!
– e.g. Leaflet JS Library
• For Web-Applications use of “non-default” headers has performance pushback for cross-domain requests
– e.g. HTTP Authorization header on a cross-domain request causes execution of CORS (W3C Recommendation) => Pre-flight request…

Principle #17a - Use IANA well-known identifiers

I need more details to understand the intention of this principle. Could you provide more details. In particular I do not understand the reference to IANA. Lets continue discussing.

Principle #12 – Not Accessing Resources

• Use verbs to offer operations on resources
• /v1/transform
• Example to transform feature using different CRS
– /v1/transform/features/highway/A8?fromCRS=4326&toCRS=WGS84