feat: support "host" resources #62

marcofriso · 2020-03-18T12:39:34Z

Update the specification at to include "Server Element" structure described by OAS 3 format (https://swagger.io/docs/specification/api-host-and-base-path/).

As reported on Swagger website:

"In OpenAPI 3.0, you use the servers array to specify one or more base URLs for your API. servers replaces the host, basePath and schemes keywords used in OpenAPI 2.0. Each server has an url and an optional Markdown-formatted description."

In OAS 3.0 a simple server looks like this:

servers:
  - url: '{protocol}://api.example.com'
    description: 'Description of the server'
    variables:
      protocol:
        enum:
          - http
          - https
        default: https

In Api Elements a server should contain a href and optionally hrefVariables.
A simple OAS3 server would map to a server element like this:

element: server
meta:
  description: Production
attributes:
  href: https://example.com/

For more information about the design please check the following link → #53 (comment)

UPDATE
→ after talk to @tjanc I am going to remove server object and introduce hosts classification under "Resource" and "Category"

Closes APIARY-5854

marcofriso · 2020-03-18T12:42:23Z

I am not completely sure about this one...

docs/element-definitions.md

marcofriso · 2020-03-24T11:53:57Z

In the last commit server object has been replaced by classification hosts under resource and category elements.

tjanc · 2020-03-24T15:12:00Z

docs/element-definitions.md

@@ -1139,6 +1139,10 @@ The Resource representation with its available transitions and its data.

        The `content` MUST NOT include more than one `Data Structure`.

+#### Classifications
+
+- `"hosts"` - Resource is a set of servers.


Should be
"host" - Resource is a host description

Also, explain what a "host" resource is in the description of the resource element (L1123).
Something like "A resource element classified as host SHALL be interpreted as...".

I am not sure if this has been implemented in the end as in Resource we have hosts

docs/element-definitions.md

kylef

I've made a couple of suggestions, one is regarding adding the hosts attribute to both Resource and Transition. This is to support the OpenAPI feature of overriding the host at the resource or transition element.

The other is to include further semantics and explanation for the reader for the host resource classification.

In terms of API Elements JS, we likely want to add the following:

hosts property to Category which looks for hosts categories, something like item.classes.contains(‘hosts’).
hosts property on Resource which looks in this.attributes for the hosts category.
hosts property on Transition which looks in this.attributes for the hosts category.

docs/element-definitions.md

- for Resource and Transition - refactoring

kylef

This looks good to me, I'll let @tjanc have another look before we merge otherwise looks great 👍.

tjanc

Some wording/fixes. @kylef feedback appreciated, my the english is not the perfectest.
Also, @marcofriso please add an entry to the overview here:
https://github.com/apiaryio/api-elements/blob/master/docs/overview.md#relationship-of-elements
Something like

Category (Group of Resource Elements representing hosts)

after

Category (Group of Resource Elements)
Category (Group of Authentication and Authorization Scheme Definitions)

tjanc · 2020-03-31T09:14:08Z

docs/element-definitions.md

@@ -1126,11 +1126,17 @@ The Resource representation with its available transitions and its data.

 - `element` - `"resource"`
 - `attributes`
+    - `hosts` ([Array][][[Resource][]]).
+
+        Resources in the hosts attribute SHOULD implicitly be treated as they have the `host` resource classification.


Perhaps

Optional list of host resources. Every entry SHALL be interpreted as if classified as `host`. _See `host` classification in [Resource][] for further semantics._ Overrides any otherwise relevant `hosts` definitions.

@kylef what do you think (wording)?

what's the difference between SHALL and SHOULD in these circumstances?

SHALL describes a requirement. SHOULD describes a recommendation. See RFC 2119.
I think we should require any interpreter of APIE to see these entries as hosts.

tjanc · 2020-03-31T09:51:25Z

docs/element-definitions.md

+
+        Definition of any input message-body attribute for this transition.
+
+    - `hosts` ([Array][][[Transition][]]).


I think this should be

`hosts` ([Array][][[Resource][]])

Also, wording, similar to above comment:

Optional list of host resources. Every entry SHALL be interpreted as if classified as `host`. _See `host` classification in [Resource][] for further semantics._ All [Resource][]s nested under the [Transition][]'s `content` SHALL interpret this `hosts` definition as their own, unless it is overridden by another `hosts` definition on the path to the [Resource][] element.

@kylef feedback appreciated

moved 'See host classification in [Resource][] for further semantics.' at the end of the paragraph.

tjanc · 2020-03-31T13:19:03Z

docs/element-definitions.md

+- `"host"` - A host transition represents the "root" of the API transition. 
+    The transition href MAY be append to the host href to create a absolute URI.
+    A transition that has a `host` classification MUST be a root component of a URI.
+


A transition cannot be a host no? Just a resource. I think we can remove this paragraph.

Being application state transitions ("Transitions") resource operations should we include here the Category of Hosts at all (#53 (comment))?

tjanc · 2020-03-31T13:21:33Z

docs/element-definitions.md

 - `"dataStructures"` - Category is a set of data structures.
+- `"hosts"` - Category of [Resource][] or [Transition][] which implicitly contain the respective `host` classification.


Wording:

Category of [Resource][]s interpreted as a list of host resources of an API. Every entry SHALL be interpreted as if classified as `host`. _See `host` classification in [Resource][] for further semantics._

marcofriso · 2020-03-31T14:03:22Z

I see also some of the internal links have to be changed as they don't work

docs: add server object to element-definitions

184a297

Closes APIARY-5854

marcofriso force-pushed the marco/server-object-definition branch from 6f683ac to 184a297 Compare March 18, 2020 12:41

marcofriso requested a review from a team March 18, 2020 12:41

kylef requested changes Mar 23, 2020

View reviewed changes

marcofriso requested review from tjanc and removed request for tjanc March 24, 2020 11:24

docs: set hosts classifications to element-definitions

fd8b309

marcofriso requested a review from a team March 24, 2020 11:54

marcofriso changed the title ~~docs: add server object to element-definitions~~ docs: add server support to element-definitions Mar 24, 2020

docs: set host classifications to element-definitions

72f8419

tjanc suggested changes Mar 25, 2020

View reviewed changes

kylef reviewed Mar 25, 2020

View reviewed changes

docs/element-definitions.md Outdated Show resolved Hide resolved

docs/element-definitions.md Show resolved Hide resolved

docs: set hosts attribute and host classification

66dcf39

- for Resource and Transition - refactoring

marcofriso force-pushed the marco/server-object-definition branch from e6be9ae to 66dcf39 Compare March 25, 2020 11:15

docs: change hosts category description

e316aeb

marcofriso requested review from a team, tjanc and kylef and removed request for tjanc and kylef March 25, 2020 12:00

kylef requested a review from tjanc March 26, 2020 11:40

kylef approved these changes Mar 26, 2020

View reviewed changes

tjanc suggested changes Mar 31, 2020

View reviewed changes

docs: edit element-definitions and overview

e9b75cb

marcofriso requested a review from tjanc April 6, 2020 11:44

tjanc approved these changes Apr 6, 2020

View reviewed changes

kylef changed the title ~~docs: add server support to element-definitions~~ feat: support "host" resources Apr 6, 2020

kylef merged commit 2f9cebf into master Apr 6, 2020

kylef deleted the marco/server-object-definition branch April 6, 2020 12:35

marcofriso mentioned this pull request Apr 6, 2020

feat(core): add support for OAS3 Server object apiaryio/api-elements.js#428

Merged

opichals mentioned this pull request Jul 10, 2020

Does APIARY allowed Multiple Host in same project apiaryio/api-blueprint#422

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: support "host" resources #62

feat: support "host" resources #62

marcofriso commented Mar 18, 2020 •

edited

Loading

marcofriso commented Mar 18, 2020

marcofriso commented Mar 24, 2020

tjanc Mar 24, 2020

tjanc Mar 25, 2020

marcofriso Apr 6, 2020

kylef left a comment •

edited

Loading

kylef left a comment

tjanc left a comment

tjanc Mar 31, 2020

marcofriso Mar 31, 2020 •

edited

Loading

tjanc Apr 1, 2020

marcofriso Apr 3, 2020

tjanc Mar 31, 2020

marcofriso Apr 3, 2020

marcofriso Apr 3, 2020 •

edited

Loading

tjanc Mar 31, 2020

marcofriso Mar 31, 2020 •

edited

Loading

marcofriso Apr 3, 2020

tjanc Mar 31, 2020

marcofriso Apr 3, 2020

marcofriso commented Mar 31, 2020


		Definition of any input message-body attribute for this transition.

		- `hosts` ([Array][][[Transition][]]).

		- `"dataStructures"` - Category is a set of data structures.
		- `"hosts"` - Category of [Resource][] or [Transition][] which implicitly contain the respective `host` classification.

feat: support "host" resources #62

feat: support "host" resources #62

Conversation

marcofriso commented Mar 18, 2020 • edited Loading

marcofriso commented Mar 18, 2020

marcofriso commented Mar 24, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kylef left a comment • edited Loading

Choose a reason for hiding this comment

kylef left a comment

Choose a reason for hiding this comment

tjanc left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

marcofriso Mar 31, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

marcofriso Apr 3, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

marcofriso Mar 31, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

marcofriso commented Mar 31, 2020

marcofriso commented Mar 18, 2020 •

edited

Loading

kylef left a comment •

edited

Loading

marcofriso Mar 31, 2020 •

edited

Loading

marcofriso Apr 3, 2020 •

edited

Loading

marcofriso Mar 31, 2020 •

edited

Loading