opengeospatial / ogc-web-api-guidelines Goto Github PK
View Code? Open in Web Editor NEWLicense: Apache License 2.0
License: Apache License 2.0
• 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“: „...“
}
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.
• 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
An additional principle from the Testbed 12 REST User Guide
idem
• 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
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".
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.
• 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
see Linda's comment in #23
• 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
• Describe the API in OpenAPI has value to the developer
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.
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?
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.
In the title of principle 10: Allow felxible Content Negotiation
• Host your API on HTTPS
• Require OAuth2 Bearer Tokens to control access
• Use OpenID Connect to fetch use claims
The links to the latest published version near the top of the README go nowhere. The links should be updated or removed.
• 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!
• 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
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.
• 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
Please consider bulk operations on thousands of features at the same time (read, update, ...) pagination is not enough
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?
• 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
Should include HTTP status code 302 in Option Set #2.
302 is used by opengis.net to support persistence in URIs (through redirection).
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 ?
• Aspects that are already solved in main-stream IT, simply adopt
• Just domain specific aspects – And that will be a lot…
An additional principle from the Testbed 12 Rest User Guide
This issue is for the general discussion of the OGC Design Principles
Purpose is to develop a section to modular Web API to make readers understand the context.
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.
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.
Carl submitted comments as red-lines to a Word version of the API Guidelines document. It can be found in the Comments folder.
Change the requirements section to recommendations. Recommendations should be testable but not normative.
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
Should we reserve some paths for some "Common" cases and special meanings?. Can this be and added principle?
For example:
/api
/conformance
/collections
/metadata
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
It should be deterministic what document is going to be returned when a URI is opened.
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).
• 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
For each principle, clearly separate which text is the principle / "normative" and what is discussed / informative explanation.
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.
• 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…
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.
• 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
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.