Comments (7)
@klokane I think this can be solved with 'One Of', and enum, for example the MSON-pseudo code, the hrefVariables can be represented using selection:
- One Of
- (object) - Production
- schema: https (fixed)
- host: example.com (fixed)
- (object) - Development
- schema: http (fixed)
- host: dev.example.com (fixed)
- (object) - Production
I think you can imagine how that could be reproduced in the above element structure (didn't want to write extend/select API Elements by hand).
There can also simpler variant with enum, providing it is only one value that is changed:
element: server
attributes:
href: https://{environment}/
hrefVariables:
element: object
content:
- element: member
content:
key: environment
value:
type: enum
attributes:
enumerations:
- element: string
meta:
title:
element: string
content: Development
content: dev.example.com
- element: string
meta:
title:
element: string
content: Production
content: example.com
from api-elements.
I was thinking we could introduce a concept of "Server" into API Elements which is similiar to OpenAPI 3. A server could contain a href, and optionally hrefVariables. The href is a URI template (template href). For example a simple OAS3 server would map to a server element:
element: server
meta:
description: Production
attributes:
href: https://example.com/
Templated variables may look as follows:
element: server
attributes:
href: {scheme}://example.com/
hrefVariables:
element: object
content:
- element: member
content:
key: scheme
value:
element: enum
attributes:
enumerations:
- http
- https
A server MAY be inside a resource, or inside an API Category. The API Category may contain a "servers" category to group all available servers.
Tools such as API Documentation, API Consoles SHOULD make use of this information. Tools like API Gateways MAY utilise this information.
It should be possible to supply the server information at run-time to tooling, for example a console or documentation renderer should allow me to inject certain server information. The use-case is that it can inject mock-servers, or other tooling for example a configured API Gateway can populate server information to documentation renderer.
Mapping to other formats
API Blueprint
API Blueprint doesn't contain deployment information and thus does not emit any server elements.
NOTE, some have defined semantics for HOST
as a metadata in API Blueprint. This will stay as-is, this is NOT a feature of API Blueprint and we want to keep the seperation of deployment information out of the API Blueprint language. It will not be mapped to servers object. HOST
is NOT a feature of API Blueprint.
Swagger 2
The schemes
, host
, basePath
is mapped into a server object similiar to the following:
element: server
attributes:
href: {scheme}://{host}/{basePath}
hrefVariables:
element: object
content:
- element: member
content:
key: scheme
- element: member
content:
key: host
- element: member
content:
key: basePath
As some of these fields are optional in Swagger 2, they may not have a value. schemes
will be mapped to either a fixed value or a enumeration of values. Similiary host
and basePath
will be mapped to variables in the server object.
OpenAPI 3
There is direct mapping between OAS 'Server Object' and server API Element.
from api-elements.
Following some discussions in OpenAPI, there is some consensus that servers
is perhaps a poor name (https://open-api.slack.com/archives/C1137F8HF/p1559929905003800), and hosts
, backends
or similiar may be a better fit.
from api-elements.
What about ability set uri templates part in depencies on type of enviroment eg.
- production:
- scheme: https
- dev:
- scheme: http
- tld: local
from api-elements.
Nice idea, maybe we should introduce standardized way howto place this into Blueprint to allow tooling work with. In relation to enviroment variables, it can be good idea for dredd (cc @honzajavorek)
from api-elements.
There's a proof of concept implementation for OpenAPI 2 parser at apiaryio/api-elements.js@50dc494.
from api-elements.
I had some discussions with @tjanc who proposed we should re-use the "resource" element because it already contains href
and hrefVariables
. Semantically, a server IS a resource. Therefore we can use the existing Resource Element instead of introducing a new element. To be able to differentiate the resource element from other resources, we can add an additional classifier of host
to represent it is a host.
element: resource
meta:
classes:
- host
attributes:
href: {scheme}://example.com/
hrefVariables:
element: hrefVariables
content:
- element: member
content:
key: scheme
value:
element: enum
attributes:
enumerations:
- http
- https
In terms of a category of these types of resources, we can have a hosts
category which looks as follows:
element: category
meta:
classes:
- hosts
content:
- element: resource
meta:
classes:
- host
attributes:
href: {scheme}://example.com/
hrefVariables:
element: hrefVariables
content:
- element: member
content:
key: scheme
value:
element: enum
attributes:
enumerations:
- http
- https
OpenAPI 3 also supports attaching a set of "Server Object"s to a resource (Path Item Object) or a transition (Operation Object). As such, in this case we can introduce a hosts
attribute to "Resource Element" and "Transition Element" as follows:
element: resource
attributes:
href: /foo
hosts:
element: category
content:
- element: resource
meta:
classes:
- host
attributes:
href: {scheme}://example.com/
hrefVariables:
element: hrefVariables
content:
- element: member
content:
key: scheme
value:
element: enum
attributes:
enumerations:
- http
- https
The existing API Elements referencing is also possible, thus:
element: resource
meta:
id:
element: string
content: productionServer
can be referenced:
element: productionServer
To summarise, API Element may offer the following:
- New "Resource" classification
host
- New "Category" classification
hosts
- New property
hosts
onResource
andTransition
elements to contain Category of hosts.
from api-elements.
Related Issues (20)
- Guidelines on how to use copy and description
- Single API Elements Package HOT 1
- Hypermedia Affordances
- Annotation "fixits" HOT 1
- Remove `annotation` code HOT 7
- Clarify source map type HOT 11
- Support files in Source Map
- Multiple responses HOT 3
- Provide information about the source ADD format and version HOT 2
- Document the migration path and changes between API Elements 0.6 and 1.0 HOT 3
- Make `HTTP Headers` an array of `HTTP Header`
- Broken mapping
- Headings have overlapping permalinks
- Link README to production docs HOT 1
- Clarify source map line/column indexing
- API Elements evolution process
- Add repo URL for docs HOT 1
- nullable type attribute is undocumented
- Full support for expressing JSON Schema constraints in API Element data structures
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from api-elements.