From 2c7f2a4437617df4467ea4ed25093a89a426c2e2 Mon Sep 17 00:00:00 2001 From: Priya Ayyar Date: Wed, 10 Feb 2021 13:25:35 -0800 Subject: [PATCH 01/18] DOCS-10035 added the compat matrix page --- modules/ROOT/api-spec-support-api-designer.adoc | 17 +++++++++++++++++ modules/ROOT/nav.adoc | 2 ++ .../ROOT/pages/api-compatibility-matrix.adoc | 14 ++++++++++++++ 3 files changed, 33 insertions(+) create mode 100644 modules/ROOT/api-spec-support-api-designer.adoc create mode 100644 modules/ROOT/pages/api-compatibility-matrix.adoc diff --git a/modules/ROOT/api-spec-support-api-designer.adoc b/modules/ROOT/api-spec-support-api-designer.adoc new file mode 100644 index 00000000..8945d526 --- /dev/null +++ b/modules/ROOT/api-spec-support-api-designer.adoc @@ -0,0 +1,17 @@ += API Specifications Support in API Designer +ifndef::env-site,env-github[] +include::_attributes.adoc[] +endif::[] +:keywords: api, instance, manager + + +[%header%autowidth.spread,cols="a,a,a"] +|=== +| Feature | Description | RAML Implementation | OAS Implementation | API Designer Support +| Modularity | The ability to break an API specification into reusable and shared units. | | | +| API Document | The main API specification description metadata, which is the entry point for the specification. | RAML doc | OAS doc | The design of the API project +console is rendered and the document and examples are validated. +| Libraries | The unit containing collections of related reusable description elements. | RAML library | Implemented indirectly using an empty spec. Only components are supported in the OAS doc. | +Edited as a stand-alone project. Supports the reuse of the module in an API project. +| Fragments | Stand-alone piece of the spec describing a specific element | +|=== \ No newline at end of file diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index f46d5bc0..39928ce5 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -8,6 +8,8 @@ ** xref:api-led-deploy.adoc[Step 5. Deploy the API to CloudHub] ** xref:api-led-operate.adoc[Step 6. Operate the API] * xref:intro-platform-hosting.adoc[Hosting Options] +* xref:api-compatibility-matrix.adoc[Anypoint Platform Compatibility Support for Restful-APIs by Products] + ** xref:api-spec-support-api-designer.adoc[API Designer] * xref:browser-support.adoc[Browser Support] * xref:glossary.adoc[Glossary] * xref:contribute.adoc[Contribute to MuleSoft Documentation] diff --git a/modules/ROOT/pages/api-compatibility-matrix.adoc b/modules/ROOT/pages/api-compatibility-matrix.adoc new file mode 100644 index 00000000..b4187ad1 --- /dev/null +++ b/modules/ROOT/pages/api-compatibility-matrix.adoc @@ -0,0 +1,14 @@ += Anypoint Platform Compatibility Support for Restful-APIs +ifndef::env-site,env-github[] +include::_attributes.adoc[] +endif::[] + +You can design an API in Anypoint Platform using a RESTful API Modeling Language (RAML) or an OpenAPI Specification (OAS) format based on your needs. Both RAML and OAS specifications implement an almost-RESTful API model and are equivalent in terms of the features they provide, except for the introduction of the callback support in OAS 3.0. + +RAML, which is optimized for design and reusability, implements _syntactic sugar_ to make descriptions smaller. Conversely, OAS enables you to simulate the components and libraries. + +MuleSoft API Tooling, which includes parser AMF and Language server (ALS), provides interoperability using common metadata model and enables data definition reuse, use of linting rules, and provides spec translation in both RAMl and OAS specifications. + +You can learn more about how each of the specification features are implemented in the Anypoint Platform products: + +API Specifications Support in API Designer From e1462e3c2cd8695b718bc7afaeb73bad60fa115f Mon Sep 17 00:00:00 2001 From: Priya Ayyar Date: Wed, 10 Feb 2021 14:43:23 -0800 Subject: [PATCH 02/18] DOCS-10035 made updates --- modules/ROOT/pages/api-compatibility-matrix.adoc | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/api-compatibility-matrix.adoc b/modules/ROOT/pages/api-compatibility-matrix.adoc index b4187ad1..fbd268c3 100644 --- a/modules/ROOT/pages/api-compatibility-matrix.adoc +++ b/modules/ROOT/pages/api-compatibility-matrix.adoc @@ -3,12 +3,13 @@ ifndef::env-site,env-github[] include::_attributes.adoc[] endif::[] -You can design an API in Anypoint Platform using a RESTful API Modeling Language (RAML) or an OpenAPI Specification (OAS) format based on your needs. Both RAML and OAS specifications implement an almost-RESTful API model and are equivalent in terms of the features they provide, except for the introduction of the callback support in OAS 3.0. +You can design an API in Anypoint Platform using a RESTful API Modeling Language (RAML) or an OpenAPI Specification (OAS) format based on your needs. Both RAML and OAS specifications implement an almost-RESTful API model and are equivalent in terms of the features they provide, except for the callback support in OAS 3.0. RAML, which is optimized for design and reusability, implements _syntactic sugar_ to make descriptions smaller. Conversely, OAS enables you to simulate the components and libraries. MuleSoft API Tooling, which includes parser AMF and Language server (ALS), provides interoperability using common metadata model and enables data definition reuse, use of linting rules, and provides spec translation in both RAMl and OAS specifications. -You can learn more about how each of the specification features are implemented in the Anypoint Platform products: +You can learn more about how each of the specification features are implemented in Anypoint Platform products: + +* xref:api-spec-support-api-designer.adoc[API Specifications Support in API Designer] -API Specifications Support in API Designer From 0be0ac404be103f3e1d65949aa70e9d8d339608a Mon Sep 17 00:00:00 2001 From: Priya Ayyar Date: Tue, 16 Feb 2021 20:17:47 -0800 Subject: [PATCH 03/18] DOCS-10035-made updates --- .../ROOT/api-spec-support-api-designer.adoc | 17 --------- .../ROOT/pages/api-compatibility-matrix.adoc | 8 ++-- .../pages/api-spec-support-api-designer.adoc | 38 +++++++++++++++++++ 3 files changed, 43 insertions(+), 20 deletions(-) delete mode 100644 modules/ROOT/api-spec-support-api-designer.adoc create mode 100644 modules/ROOT/pages/api-spec-support-api-designer.adoc diff --git a/modules/ROOT/api-spec-support-api-designer.adoc b/modules/ROOT/api-spec-support-api-designer.adoc deleted file mode 100644 index 8945d526..00000000 --- a/modules/ROOT/api-spec-support-api-designer.adoc +++ /dev/null @@ -1,17 +0,0 @@ -= API Specifications Support in API Designer -ifndef::env-site,env-github[] -include::_attributes.adoc[] -endif::[] -:keywords: api, instance, manager - - -[%header%autowidth.spread,cols="a,a,a"] -|=== -| Feature | Description | RAML Implementation | OAS Implementation | API Designer Support -| Modularity | The ability to break an API specification into reusable and shared units. | | | -| API Document | The main API specification description metadata, which is the entry point for the specification. | RAML doc | OAS doc | The design of the API project -console is rendered and the document and examples are validated. -| Libraries | The unit containing collections of related reusable description elements. | RAML library | Implemented indirectly using an empty spec. Only components are supported in the OAS doc. | -Edited as a stand-alone project. Supports the reuse of the module in an API project. -| Fragments | Stand-alone piece of the spec describing a specific element | -|=== \ No newline at end of file diff --git a/modules/ROOT/pages/api-compatibility-matrix.adoc b/modules/ROOT/pages/api-compatibility-matrix.adoc index fbd268c3..48c21551 100644 --- a/modules/ROOT/pages/api-compatibility-matrix.adoc +++ b/modules/ROOT/pages/api-compatibility-matrix.adoc @@ -3,13 +3,15 @@ ifndef::env-site,env-github[] include::_attributes.adoc[] endif::[] -You can design an API in Anypoint Platform using a RESTful API Modeling Language (RAML) or an OpenAPI Specification (OAS) format based on your needs. Both RAML and OAS specifications implement an almost-RESTful API model and are equivalent in terms of the features they provide, except for the callback support in OAS 3.0. +You can design an API in Anypoint Platform using a RESTful API Modeling Language (RAML) or an OpenAPI Specification (OAS) format based on your needs. Both RAML and OAS specifications implement an almost-RESTful API model and provide the same features, except for the callback support in OAS 3.0. RAML, which is optimized for design and reusability, implements _syntactic sugar_ to make descriptions smaller. Conversely, OAS enables you to simulate the components and libraries. -MuleSoft API Tooling, which includes parser AMF and Language server (ALS), provides interoperability using common metadata model and enables data definition reuse, use of linting rules, and provides spec translation in both RAMl and OAS specifications. +MuleSoft API Tooling, which includes parser AMF and Language server (ALS), provides interoperability using common metadata model and enables data definition reuse, use of linting rules, and provides translation in both RAML and OAS specifications. -You can learn more about how each of the specification features are implemented in Anypoint Platform products: +Before you start designing an API, learn more about how each of the specification features are implemented in Anypoint Platform products: * xref:api-spec-support-api-designer.adoc[API Specifications Support in API Designer] +//* xref:api-spec-support-api-designer.adoc[check] + diff --git a/modules/ROOT/pages/api-spec-support-api-designer.adoc b/modules/ROOT/pages/api-spec-support-api-designer.adoc new file mode 100644 index 00000000..490e9aca --- /dev/null +++ b/modules/ROOT/pages/api-spec-support-api-designer.adoc @@ -0,0 +1,38 @@ += API Specifications Support in API Designer +ifndef::env-site,env-github[] +include::_attributes.adoc[] +endif::[] +:keywords: api, instance, manager + + +[%header%autowidth.spread,cols="a,a,a,a,a"] +|=== +| Feature | Description | RAML Implementation | OAS Implementation | API Designer Support +| Modularity | The ability to break an API specification into reusable and shared units. | Not applicable | Not applicable | Not applicable +| API Document | The main API specification description metadata, which is the entry point for the specification. | RAML doc | OAS doc | The design of the API project console is rendered and the document and examples are validated. | +| Libraries | The unit containing collections of related reusable description elements. | RAML library | Implemented indirectly using an empty specification. Only components are supported in the OAS doc. | Edited as a stand-alone project. Supports the reuse of the module in an API project. +| Fragments | Stand-alone component of the specification that describes a specific element. | RAML fragment | Implemented indirectly using an empty specification with only one declaration +or an OAS doc with a single component.| Edited as a stand-alone project and reuse of the module enabled in an API project. | +| Overlays | A partial description of the API specification that you can use to overwrite non-functional aspects of the API specification by composing it with the original specification, for example, translating the documentation to other languages. | RAML overlay | Can be simulated with JSON patch or merge tooling. | Can be edited and rendered correctly if used as main the project file.| +| Extensions | Partial description of the API spec that can be used to overwrite non-functional aspects of the API spec composing it with the original specification, like for example adding the security information for a managed API | RAML extension | Can be simulated with JSON patch or merge tooling. | Can be edited and rendered correctly if used as main the project file. +| Reusability | Ability to reuse of the API description in multiple specifications. | Not applicable | Not applicable | Not applicable +| Inline declarations and references | Ability to declare and reference elements from multiple documents. | Inclusion and name refs, RAML type, traits, resource types, and annotations declarations. | JSON-Refs and OAS components. | Autocompletion when editing and dedicated rendering provided in the console. +| Traits | Macros that extend operations in the functional model, such as pagination, that can be reused in multiple specifications for consistency | Operation macros and RAML traits | Not applicable | Autocompletion when editing and dedicated rendering in console. +| Resource types | Macros that extend resources in the functional model with complex behavior and data definition that can be reused in multiple specifications for consistency | Endpoint macros +and RAML resource types | Not applicable | Autocompletion when editing and dedicated rendering in console. +| API Metadata | *Do we need this?*| | | +| API Entrypoint | The main entry point for the API description, mostly human-readable information, such as title, version, license, and so forth. | RAML document top level information | OAS Open API object| Can be edited and validated and enables console rendering. +| Server and protocols | Actual connectivity to the service | RAML base URI information | OAS Server object | Small differences in the supported protocols +| Terms of service & licensing | User agreement and licensing information of the API | Only plain documentation | OAS Info object | +| User documentation | ? | RAML description properties in different parts of the spec | OAS different 'description' properties in the spec 'objects' +| Localized documentation | Multi-lingual descriptions | Through overlays | Not applicable | Not applicable +| Tags | Classification of parts of the specification | Only use annotations | OAS Tag object | Not applicable +| Endpoints | Resources and RPC invocations in the API | RAML resources | OAS Path Item objects under the Paths object | RAML is more RESTful, which makes it explicit in its working with resources and allowing the nesting of those resources | Allows editing and validations, and enables console rendering +| Methods and bindings to HTTP uniform interface | Operations over the resource and information about how to invoke the RPC operation | Get, Patch, Put, Post, Delete, Options, and head RAML operations | Get, Put, Post, Delete, Options, Head, Patch, Trace and fixed fields under the OAS Path Item object | Allows editing and validations, and enables console rendering +| Input parameters and HTTP bindings | Input parameters and HTTP bindings | RAML parameters | OAS Parameter object | Allows editing and validations, and enables console rendering +| Responses with multiple media types | Output parameter for the operation | RAML responses | OAS Response object | Allows editing and validations, and enables console rendering +| Responses with bindings to HTTP status codes | Binding to the HTTP status code | RAML responses | OAS Response object | Allows editing and validations, and enables console rendering +| Callbacks | Asynchronous invocations and webhooks | Not applicable | OAS Callback object | Allows editing and validations, and enables console rendering +| Links | Static connections between endpoints in the specification, excluding hyperlinks in the data | Not applicable | OAS Link object | Allows editing and validations, and enables console rendering +| +|=== \ No newline at end of file From c0f21aa14f3a327b3d801a04db32ebea614ea97d Mon Sep 17 00:00:00 2001 From: Priya Ayyar Date: Mon, 22 Feb 2021 16:17:31 -0800 Subject: [PATCH 04/18] DOCS-10035 made edits --- .../pages/api-spec-support-api-designer.adoc | 74 +++++++++++-------- 1 file changed, 45 insertions(+), 29 deletions(-) diff --git a/modules/ROOT/pages/api-spec-support-api-designer.adoc b/modules/ROOT/pages/api-spec-support-api-designer.adoc index 490e9aca..9b045676 100644 --- a/modules/ROOT/pages/api-spec-support-api-designer.adoc +++ b/modules/ROOT/pages/api-spec-support-api-designer.adoc @@ -5,34 +5,50 @@ endif::[] :keywords: api, instance, manager -[%header%autowidth.spread,cols="a,a,a,a,a"] +[%header%autowidth.spread,cols="a,a,a,a"] |=== -| Feature | Description | RAML Implementation | OAS Implementation | API Designer Support -| Modularity | The ability to break an API specification into reusable and shared units. | Not applicable | Not applicable | Not applicable -| API Document | The main API specification description metadata, which is the entry point for the specification. | RAML doc | OAS doc | The design of the API project console is rendered and the document and examples are validated. | -| Libraries | The unit containing collections of related reusable description elements. | RAML library | Implemented indirectly using an empty specification. Only components are supported in the OAS doc. | Edited as a stand-alone project. Supports the reuse of the module in an API project. -| Fragments | Stand-alone component of the specification that describes a specific element. | RAML fragment | Implemented indirectly using an empty specification with only one declaration -or an OAS doc with a single component.| Edited as a stand-alone project and reuse of the module enabled in an API project. | -| Overlays | A partial description of the API specification that you can use to overwrite non-functional aspects of the API specification by composing it with the original specification, for example, translating the documentation to other languages. | RAML overlay | Can be simulated with JSON patch or merge tooling. | Can be edited and rendered correctly if used as main the project file.| -| Extensions | Partial description of the API spec that can be used to overwrite non-functional aspects of the API spec composing it with the original specification, like for example adding the security information for a managed API | RAML extension | Can be simulated with JSON patch or merge tooling. | Can be edited and rendered correctly if used as main the project file. -| Reusability | Ability to reuse of the API description in multiple specifications. | Not applicable | Not applicable | Not applicable -| Inline declarations and references | Ability to declare and reference elements from multiple documents. | Inclusion and name refs, RAML type, traits, resource types, and annotations declarations. | JSON-Refs and OAS components. | Autocompletion when editing and dedicated rendering provided in the console. -| Traits | Macros that extend operations in the functional model, such as pagination, that can be reused in multiple specifications for consistency | Operation macros and RAML traits | Not applicable | Autocompletion when editing and dedicated rendering in console. -| Resource types | Macros that extend resources in the functional model with complex behavior and data definition that can be reused in multiple specifications for consistency | Endpoint macros -and RAML resource types | Not applicable | Autocompletion when editing and dedicated rendering in console. -| API Metadata | *Do we need this?*| | | -| API Entrypoint | The main entry point for the API description, mostly human-readable information, such as title, version, license, and so forth. | RAML document top level information | OAS Open API object| Can be edited and validated and enables console rendering. -| Server and protocols | Actual connectivity to the service | RAML base URI information | OAS Server object | Small differences in the supported protocols -| Terms of service & licensing | User agreement and licensing information of the API | Only plain documentation | OAS Info object | -| User documentation | ? | RAML description properties in different parts of the spec | OAS different 'description' properties in the spec 'objects' -| Localized documentation | Multi-lingual descriptions | Through overlays | Not applicable | Not applicable -| Tags | Classification of parts of the specification | Only use annotations | OAS Tag object | Not applicable -| Endpoints | Resources and RPC invocations in the API | RAML resources | OAS Path Item objects under the Paths object | RAML is more RESTful, which makes it explicit in its working with resources and allowing the nesting of those resources | Allows editing and validations, and enables console rendering -| Methods and bindings to HTTP uniform interface | Operations over the resource and information about how to invoke the RPC operation | Get, Patch, Put, Post, Delete, Options, and head RAML operations | Get, Put, Post, Delete, Options, Head, Patch, Trace and fixed fields under the OAS Path Item object | Allows editing and validations, and enables console rendering -| Input parameters and HTTP bindings | Input parameters and HTTP bindings | RAML parameters | OAS Parameter object | Allows editing and validations, and enables console rendering -| Responses with multiple media types | Output parameter for the operation | RAML responses | OAS Response object | Allows editing and validations, and enables console rendering -| Responses with bindings to HTTP status codes | Binding to the HTTP status code | RAML responses | OAS Response object | Allows editing and validations, and enables console rendering -| Callbacks | Asynchronous invocations and webhooks | Not applicable | OAS Callback object | Allows editing and validations, and enables console rendering -| Links | Static connections between endpoints in the specification, excluding hyperlinks in the data | Not applicable | OAS Link object | Allows editing and validations, and enables console rendering -| +| Feature: Description| RAML Implementation | OAS Implementation | API Designer Support +| Modularity: The ability to break an API specification into reusable and shared units. | Not applicable | Not applicable | Not applicable +| API Document: The main API specification description metadata, which is the entry point for the specification. | RAML doc | OAS doc | The design of the API project console is rendered and the document and examples are validated. +| Libraries: The unit containing collections of related reusable description elements. | RAML library | Implemented indirectly using an empty specification. Only components are supported in the OAS doc. | Edited as a stand-alone project. Supports the reuse of the module in an API project. +| Fragments: Stand-alone component of the specification that describes a specific element. | RAML fragment | Implemented indirectly using an empty specification with only one declaration +or an OAS doc with a single component.| Edited as a stand-alone project and reuse of the module enabled in an API project. +| Overlays: A partial description of the API specification that you can use to overwrite non-functional aspects of the API specification by composing it with the original specification, for example, translating the documentation to other languages. | RAML overlay | Can be simulated with JSON patch or merge tooling. | Can be edited and rendered correctly if used as main the project file. +| Extensions: A partial description of the API spec that can be used to overwrite non-functional aspects of the API spec composing it with the original specification, like for example adding the security information for a managed API | RAML extension | Can be simulated with JSON patch or merge tooling. | Can be edited and rendered correctly if used as main the project file. +| Reusability: The ability to reuse of the API description in multiple specifications. | Not applicable | Not applicable | Not applicable +| Inline declarations and references: The ability to declare and reference elements from multiple documents. | Inclusion and name refs, RAML type, traits, resource types, and annotations declarations. | JSON-Refs and OAS components. | Autocompletion when editing and dedicated rendering provided in the console. +| Traits: Macros that extend operations in the functional model, such as pagination, that can be reused in multiple specifications for consistency | Operation macros and RAML traits | Not applicable | Autocompletion when editing and dedicated rendering in console. +| Resource types: Macros that extend resources in the functional model with complex behavior and data definition that can be reused in multiple specifications for consistency | Endpoint macros and RAML resource types | Not applicable | Autocompletion when editing and dedicated rendering in console. +| API Metadata | *Do we need this?*| | +| API Entrypoint: The main entry point for the API description, mostly human-readable information, such as title, version, license, and so forth. | RAML document top level information | OAS Open API object| Can be edited and validated and enables console rendering. +| Server and protocols: Denotes the actual connectivity to the service | RAML base URI information | OAS Server object | Small differences in the supported protocols. +| Terms of service & licensing: The user agreement and licensing information of the API | Only plain documentation | OAS Info object | +| User documentation: ? | RAML description properties in different parts of the spec | OAS different 'description' properties in the spec 'objects' | Can be edited and validated and enables console rendering. +| Localized documentation: Specifies multi-lingual descriptions | Using overlays | Not applicable | Not applicable +| Tags: Classification of parts of the specification | Only use annotations | OAS Tag object | Not applicable +| Endpoints: Refers to the resources and RPC invocations in the API | RAML resources--RAML is more RESTful, which makes it explicit in its working with resources and allowing the nesting of those resources | OAS Path Item objects under the Paths object | Allows editing and validations, and enables console rendering. +| Methods and bindings to HTTP uniform interface: Includes operations over the resource and information about how to invoke the RPC operation. | Get, Patch, Put, Post, Delete, Options, and head RAML operations | Get, Put, Post, Delete, Options, Head, Patch, Trace and fixed fields under the OAS Path Item object | Allows editing and validations, and enables console rendering. +| Input parameters and HTTP bindings: Specifies the input parameters for the operation. | RAML parameters | OAS Parameter object | Allows editing and validations, and enables console rendering. +| Responses with multiple media types: Specifies the output parameter for the operation. | RAML responses | OAS Response object | Allows editing and validations, and enables console rendering. +| Responses with bindings to HTTP status codes: Specifies the binding to the HTTP status code. | RAML responses | OAS Response object | Allows editing and validations, and enables console rendering. +| Callbacks: Specifies the asynchronous invocations and webhooks. | Not applicable | OAS Callback object | Allows editing and validations, and enables console rendering. +| Links: Specifies the static connections between endpoints in the specification, excluding hyperlinks in the data. | Not applicable | OAS Link object | Allows editing and validations, and enables console rendering. +| OAuth 1.0: ? | RAML security schemes | Not applicable | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| OAuth 2.0: ? | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| Basic: ? | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| Digest: ? | RAML security schemes | Not applicable | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| API Key: ? | Not applicable | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| Open ID Connect: ? | Not applicable | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| Pass through: ? | RAML security schemes | Not applicable | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| Custom: ? | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| JSON schema constraints and support: ? This is the base for both. RAML Types is a superset | RAML JSON support | OAS Schema object | Allows editing and validations, and enables console rendering. +| Schema Inheritance: ? RAML types specific | RAML type inheritance | *Simulated with `$allOf`, not proper inheritance, murky situation in OAS Schema??* | Allows editing and validations, and enables console rendering. +| Type expressions: ? RAML types specific| RAML type expressions | Not applicable | Allows editing and validations, and enables console rendering. +| XML Schema constraints and support: ? | RAML XML support provided indirectly through RAML 'xml' facets for RAML types. | Support provided indirectly through XML properties for the `Schema object` | Limited editing support provided. +| Examples: ? | RAML examples | OAS `Example object` | Allows editing and validations, and enables console rendering. +| Mandatory valid examples: ? | Not applicable | Not applicable | Allows validation +| Custom property extensions: ? | Annotations | OAS specification extensions | Allows editing and validations, and enables console rendering. +| Custom node extensions: ? | Complex annotations | Not applicable | Allows editing and validations, and enables console rendering. +| Extensions schema: ? | Annotations can have a schema and can be validated |Not applicable | Allows editing and validations, and enables console rendering. +| Extensions semantics: ? | Not applicable | Not applicable | Not applicable |=== \ No newline at end of file From 9998b4697d2f318f2dff82c9c4c599e470edde94 Mon Sep 17 00:00:00 2001 From: Priya Ayyar Date: Wed, 24 Feb 2021 10:07:44 -0800 Subject: [PATCH 05/18] DOCS-10035 made edits --- modules/ROOT/pages/api-compatibility-matrix.adoc | 14 ++++++++++---- .../ROOT/pages/api-spec-support-api-designer.adoc | 1 + 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/api-compatibility-matrix.adoc b/modules/ROOT/pages/api-compatibility-matrix.adoc index 48c21551..01250024 100644 --- a/modules/ROOT/pages/api-compatibility-matrix.adoc +++ b/modules/ROOT/pages/api-compatibility-matrix.adoc @@ -3,15 +3,21 @@ ifndef::env-site,env-github[] include::_attributes.adoc[] endif::[] -You can design an API in Anypoint Platform using a RESTful API Modeling Language (RAML) or an OpenAPI Specification (OAS) format based on your needs. Both RAML and OAS specifications implement an almost-RESTful API model and provide the same features, except for the callback support in OAS 3.0. +You can design an API in Anypoint Platform using the RESTful API Modeling Language (RAML) or the OpenAPI Specification (OAS) format based on your needs. Both RAML and OAS specifications implement a similar API model and provide the same features, except for the callback support in OAS 3.0. RAML, which is optimized for design and reusability, implements _syntactic sugar_ to make descriptions smaller. Conversely, OAS enables you to simulate the components and libraries. MuleSoft API Tooling, which includes parser AMF and Language server (ALS), provides interoperability using common metadata model and enables data definition reuse, use of linting rules, and provides translation in both RAML and OAS specifications. -Before you start designing an API, learn more about how each of the specification features are implemented in Anypoint Platform products: +//Jonathan--Why are we talking about API Tooling here suddenly? also, we need to give the users any best practice guidance here? -* xref:api-spec-support-api-designer.adoc[API Specifications Support in API Designer] -//* xref:api-spec-support-api-designer.adoc[check] +Before you start designing an API, learn more about how each of the specification features are implemented and supported in Anypoint Platform products: + +* xref:api-spec-support-api-designer.adoc[API Designer] +* xref:api-spec-support-exchange.adoc[Anypoint Exchange] +* xref:api-spec-support-api-manager.adoc[API Manager] +* xref:api-spec-support-datagraph.adoc[Anypoint Datagraph] +* xref:api-spec-support-api-kit.adoc[API Kit] +* xref:api-spec-support-rest-connect.adoc[REST Connect] diff --git a/modules/ROOT/pages/api-spec-support-api-designer.adoc b/modules/ROOT/pages/api-spec-support-api-designer.adoc index 9b045676..300a2ae5 100644 --- a/modules/ROOT/pages/api-spec-support-api-designer.adoc +++ b/modules/ROOT/pages/api-spec-support-api-designer.adoc @@ -4,6 +4,7 @@ include::_attributes.adoc[] endif::[] :keywords: api, instance, manager +You can implement your API specification in a way that best suits your needs. The following table explains how each of the features of the API specification is best implemented and the level of support provided for the specification in API Designer. [%header%autowidth.spread,cols="a,a,a,a"] |=== From 97c51a9910bf2cc1a8b5ee39d29b3df63aed9698 Mon Sep 17 00:00:00 2001 From: Priya Ayyar Date: Fri, 19 Mar 2021 13:58:45 -0700 Subject: [PATCH 06/18] DOCS-10035 made edits --- .../ROOT/pages/api-compatibility-matrix.adoc | 8 ++---- .../pages/api-spec-support-api-designer.adoc | 25 +++++++++++-------- 2 files changed, 16 insertions(+), 17 deletions(-) diff --git a/modules/ROOT/pages/api-compatibility-matrix.adoc b/modules/ROOT/pages/api-compatibility-matrix.adoc index 01250024..1c5ba4fd 100644 --- a/modules/ROOT/pages/api-compatibility-matrix.adoc +++ b/modules/ROOT/pages/api-compatibility-matrix.adoc @@ -3,13 +3,9 @@ ifndef::env-site,env-github[] include::_attributes.adoc[] endif::[] -You can design an API in Anypoint Platform using the RESTful API Modeling Language (RAML) or the OpenAPI Specification (OAS) format based on your needs. Both RAML and OAS specifications implement a similar API model and provide the same features, except for the callback support in OAS 3.0. +You can design an API in Anypoint Platform using the RESTful API Modeling Language (RAML) or the OpenAPI Specification (OAS) format based on your needs. Both RAML and OAS specifications have a common REST API model and provide similar features. -RAML, which is optimized for design and reusability, implements _syntactic sugar_ to make descriptions smaller. Conversely, OAS enables you to simulate the components and libraries. - -MuleSoft API Tooling, which includes parser AMF and Language server (ALS), provides interoperability using common metadata model and enables data definition reuse, use of linting rules, and provides translation in both RAML and OAS specifications. - -//Jonathan--Why are we talking about API Tooling here suddenly? also, we need to give the users any best practice guidance here? +MuleSoft's underlying metadata libraries and components, which includes AMF (parser) and ALS (language server for IDEs), provides interoperability using a common metadata model and enables data definition reuse, use of linting rules, and provides translation to and from both RAML and OAS specifications. Before you start designing an API, learn more about how each of the specification features are implemented and supported in Anypoint Platform products: diff --git a/modules/ROOT/pages/api-spec-support-api-designer.adoc b/modules/ROOT/pages/api-spec-support-api-designer.adoc index 300a2ae5..75ddf0a5 100644 --- a/modules/ROOT/pages/api-spec-support-api-designer.adoc +++ b/modules/ROOT/pages/api-spec-support-api-designer.adoc @@ -9,24 +9,24 @@ You can implement your API specification in a way that best suits your needs. Th [%header%autowidth.spread,cols="a,a,a,a"] |=== | Feature: Description| RAML Implementation | OAS Implementation | API Designer Support -| Modularity: The ability to break an API specification into reusable and shared units. | Not applicable | Not applicable | Not applicable -| API Document: The main API specification description metadata, which is the entry point for the specification. | RAML doc | OAS doc | The design of the API project console is rendered and the document and examples are validated. -| Libraries: The unit containing collections of related reusable description elements. | RAML library | Implemented indirectly using an empty specification. Only components are supported in the OAS doc. | Edited as a stand-alone project. Supports the reuse of the module in an API project. -| Fragments: Stand-alone component of the specification that describes a specific element. | RAML fragment | Implemented indirectly using an empty specification with only one declaration -or an OAS doc with a single component.| Edited as a stand-alone project and reuse of the module enabled in an API project. -| Overlays: A partial description of the API specification that you can use to overwrite non-functional aspects of the API specification by composing it with the original specification, for example, translating the documentation to other languages. | RAML overlay | Can be simulated with JSON patch or merge tooling. | Can be edited and rendered correctly if used as main the project file. -| Extensions: A partial description of the API spec that can be used to overwrite non-functional aspects of the API spec composing it with the original specification, like for example adding the security information for a managed API | RAML extension | Can be simulated with JSON patch or merge tooling. | Can be edited and rendered correctly if used as main the project file. -| Reusability: The ability to reuse of the API description in multiple specifications. | Not applicable | Not applicable | Not applicable -| Inline declarations and references: The ability to declare and reference elements from multiple documents. | Inclusion and name refs, RAML type, traits, resource types, and annotations declarations. | JSON-Refs and OAS components. | Autocompletion when editing and dedicated rendering provided in the console. ++4| Modularity: The ability to break an API specification into reusable and shared units. +| API Document: The main API specification description metadata, which is the entry point for the specification. | RAML root document | OAS root document | The design of the API project console is rendered and the document and examples are validated. +| Libraries: The unit containing collections of related reusable description elements. | RAML library | Can be implemented using an empty OAS specification containing multiple components. | Edited as a stand-alone project. Supports the reuse of the module in an API project. +| Fragments: Stand-alone component of the specification that describes a specific element. | RAML fragment | Can be implemented using an empty OAS specification containing a single component.| Edited as a stand-alone project. Supports the reuse of the module in an API project. +| Overlays: A partial description of the API specification that you can use to overwrite non-functional aspects of the API specification by composing it with the original specification, for example, translating the documentation to other languages. | RAML overlay | Can be simulated with JSON patch or merge preprocessing. | Can be edited and rendered correctly if used as main the project file. +| Extensions: A partial description of the API spec that can be used to overwrite non-functional aspects of the API spec composing it with the original specification, like for example adding the security information for a managed API | RAML extension | Can be simulated with JSON patch or merge preprocessing. | Can be edited and rendered correctly if used as main the project file. ++4| Reusability: The ability to reuse of the API description in multiple specifications. +| Inline declarations and references: The ability to declare and reference elements from multiple documents. | Inclusion and named references to: datatypes, traits, resource types, and annotations declarations. | JSON reference and OAS components. | Autocompletion when editing and dedicated rendering provided in the console. | Traits: Macros that extend operations in the functional model, such as pagination, that can be reused in multiple specifications for consistency | Operation macros and RAML traits | Not applicable | Autocompletion when editing and dedicated rendering in console. | Resource types: Macros that extend resources in the functional model with complex behavior and data definition that can be reused in multiple specifications for consistency | Endpoint macros and RAML resource types | Not applicable | Autocompletion when editing and dedicated rendering in console. -| API Metadata | *Do we need this?*| | ++4| API Metadata: Part of the specification for humans//Jonathan--what does this mean? | API Entrypoint: The main entry point for the API description, mostly human-readable information, such as title, version, license, and so forth. | RAML document top level information | OAS Open API object| Can be edited and validated and enables console rendering. | Server and protocols: Denotes the actual connectivity to the service | RAML base URI information | OAS Server object | Small differences in the supported protocols. | Terms of service & licensing: The user agreement and licensing information of the API | Only plain documentation | OAS Info object | -| User documentation: ? | RAML description properties in different parts of the spec | OAS different 'description' properties in the spec 'objects' | Can be edited and validated and enables console rendering. +| User documentation: ? | RAML description properties in different parts of the specification | OAS description properties in the specification objects | Can be edited and validated and enables console rendering. | Localized documentation: Specifies multi-lingual descriptions | Using overlays | Not applicable | Not applicable | Tags: Classification of parts of the specification | Only use annotations | OAS Tag object | Not applicable ++4| Functional model: definition--what does this mean? | Endpoints: Refers to the resources and RPC invocations in the API | RAML resources--RAML is more RESTful, which makes it explicit in its working with resources and allowing the nesting of those resources | OAS Path Item objects under the Paths object | Allows editing and validations, and enables console rendering. | Methods and bindings to HTTP uniform interface: Includes operations over the resource and information about how to invoke the RPC operation. | Get, Patch, Put, Post, Delete, Options, and head RAML operations | Get, Put, Post, Delete, Options, Head, Patch, Trace and fixed fields under the OAS Path Item object | Allows editing and validations, and enables console rendering. | Input parameters and HTTP bindings: Specifies the input parameters for the operation. | RAML parameters | OAS Parameter object | Allows editing and validations, and enables console rendering. @@ -34,6 +34,7 @@ or an OAS doc with a single component.| Edited as a stand-alone project and reus | Responses with bindings to HTTP status codes: Specifies the binding to the HTTP status code. | RAML responses | OAS Response object | Allows editing and validations, and enables console rendering. | Callbacks: Specifies the asynchronous invocations and webhooks. | Not applicable | OAS Callback object | Allows editing and validations, and enables console rendering. | Links: Specifies the static connections between endpoints in the specification, excluding hyperlinks in the data. | Not applicable | OAS Link object | Allows editing and validations, and enables console rendering. ++4| Security model: definition--what does this mean? | OAuth 1.0: ? | RAML security schemes | Not applicable | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. | OAuth 2.0: ? | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. | Basic: ? | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. @@ -42,12 +43,14 @@ or an OAS doc with a single component.| Edited as a stand-alone project and reus | Open ID Connect: ? | Not applicable | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. | Pass through: ? | RAML security schemes | Not applicable | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. | Custom: ? | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. ++4| Data description and validation: definition--what does this mean? | JSON schema constraints and support: ? This is the base for both. RAML Types is a superset | RAML JSON support | OAS Schema object | Allows editing and validations, and enables console rendering. | Schema Inheritance: ? RAML types specific | RAML type inheritance | *Simulated with `$allOf`, not proper inheritance, murky situation in OAS Schema??* | Allows editing and validations, and enables console rendering. | Type expressions: ? RAML types specific| RAML type expressions | Not applicable | Allows editing and validations, and enables console rendering. | XML Schema constraints and support: ? | RAML XML support provided indirectly through RAML 'xml' facets for RAML types. | Support provided indirectly through XML properties for the `Schema object` | Limited editing support provided. | Examples: ? | RAML examples | OAS `Example object` | Allows editing and validations, and enables console rendering. | Mandatory valid examples: ? | Not applicable | Not applicable | Allows validation ++4| Meta-model extensibility: Defines the ability to extend the format to describe additional details or objects. | Custom property extensions: ? | Annotations | OAS specification extensions | Allows editing and validations, and enables console rendering. | Custom node extensions: ? | Complex annotations | Not applicable | Allows editing and validations, and enables console rendering. | Extensions schema: ? | Annotations can have a schema and can be validated |Not applicable | Allows editing and validations, and enables console rendering. From dc16024f88553f4781599a7bbac2e8851faa6b5a Mon Sep 17 00:00:00 2001 From: Priya Ayyar Date: Tue, 30 Mar 2021 13:59:24 -0700 Subject: [PATCH 07/18] DOCS-10035 made edits --- .../pages/api-spec-support-api-designer.adoc | 48 +++++++++---------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/modules/ROOT/pages/api-spec-support-api-designer.adoc b/modules/ROOT/pages/api-spec-support-api-designer.adoc index 75ddf0a5..f89b908f 100644 --- a/modules/ROOT/pages/api-spec-support-api-designer.adoc +++ b/modules/ROOT/pages/api-spec-support-api-designer.adoc @@ -19,40 +19,40 @@ You can implement your API specification in a way that best suits your needs. Th | Inline declarations and references: The ability to declare and reference elements from multiple documents. | Inclusion and named references to: datatypes, traits, resource types, and annotations declarations. | JSON reference and OAS components. | Autocompletion when editing and dedicated rendering provided in the console. | Traits: Macros that extend operations in the functional model, such as pagination, that can be reused in multiple specifications for consistency | Operation macros and RAML traits | Not applicable | Autocompletion when editing and dedicated rendering in console. | Resource types: Macros that extend resources in the functional model with complex behavior and data definition that can be reused in multiple specifications for consistency | Endpoint macros and RAML resource types | Not applicable | Autocompletion when editing and dedicated rendering in console. -+4| API Metadata: Part of the specification for humans//Jonathan--what does this mean? ++4| API Metadata: Provides metadata about the API that might be used by tooling as required. | API Entrypoint: The main entry point for the API description, mostly human-readable information, such as title, version, license, and so forth. | RAML document top level information | OAS Open API object| Can be edited and validated and enables console rendering. | Server and protocols: Denotes the actual connectivity to the service | RAML base URI information | OAS Server object | Small differences in the supported protocols. | Terms of service & licensing: The user agreement and licensing information of the API | Only plain documentation | OAS Info object | -| User documentation: ? | RAML description properties in different parts of the specification | OAS description properties in the specification objects | Can be edited and validated and enables console rendering. +| User documentation: Includes user guide and reference material that clarifies how the API works. | RAML description properties in different parts of the specification | OAS description properties in the specification objects | Can be edited and validated and enables console rendering. | Localized documentation: Specifies multi-lingual descriptions | Using overlays | Not applicable | Not applicable | Tags: Classification of parts of the specification | Only use annotations | OAS Tag object | Not applicable -+4| Functional model: definition--what does this mean? -| Endpoints: Refers to the resources and RPC invocations in the API | RAML resources--RAML is more RESTful, which makes it explicit in its working with resources and allowing the nesting of those resources | OAS Path Item objects under the Paths object | Allows editing and validations, and enables console rendering. ++4| Functional model: A declaration of the resources to use when RPCs are invoked. +| Endpoints: Refers to the resources and RPC invocations in the API | Because RAML is more RESTful, the RAML resources are more explicit in its working and allows for the nesting of those resources. | OAS Path Item objects under the Paths object | Allows editing and validations, and enables console rendering. | Methods and bindings to HTTP uniform interface: Includes operations over the resource and information about how to invoke the RPC operation. | Get, Patch, Put, Post, Delete, Options, and head RAML operations | Get, Put, Post, Delete, Options, Head, Patch, Trace and fixed fields under the OAS Path Item object | Allows editing and validations, and enables console rendering. | Input parameters and HTTP bindings: Specifies the input parameters for the operation. | RAML parameters | OAS Parameter object | Allows editing and validations, and enables console rendering. | Responses with multiple media types: Specifies the output parameter for the operation. | RAML responses | OAS Response object | Allows editing and validations, and enables console rendering. | Responses with bindings to HTTP status codes: Specifies the binding to the HTTP status code. | RAML responses | OAS Response object | Allows editing and validations, and enables console rendering. | Callbacks: Specifies the asynchronous invocations and webhooks. | Not applicable | OAS Callback object | Allows editing and validations, and enables console rendering. | Links: Specifies the static connections between endpoints in the specification, excluding hyperlinks in the data. | Not applicable | OAS Link object | Allows editing and validations, and enables console rendering. -+4| Security model: definition--what does this mean? -| OAuth 1.0: ? | RAML security schemes | Not applicable | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. -| OAuth 2.0: ? | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. -| Basic: ? | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. -| Digest: ? | RAML security schemes | Not applicable | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. -| API Key: ? | Not applicable | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. -| Open ID Connect: ? | Not applicable | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. -| Pass through: ? | RAML security schemes | Not applicable | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. -| Custom: ? | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. -+4| Data description and validation: definition--what does this mean? -| JSON schema constraints and support: ? This is the base for both. RAML Types is a superset | RAML JSON support | OAS Schema object | Allows editing and validations, and enables console rendering. -| Schema Inheritance: ? RAML types specific | RAML type inheritance | *Simulated with `$allOf`, not proper inheritance, murky situation in OAS Schema??* | Allows editing and validations, and enables console rendering. -| Type expressions: ? RAML types specific| RAML type expressions | Not applicable | Allows editing and validations, and enables console rendering. -| XML Schema constraints and support: ? | RAML XML support provided indirectly through RAML 'xml' facets for RAML types. | Support provided indirectly through XML properties for the `Schema object` | Limited editing support provided. -| Examples: ? | RAML examples | OAS `Example object` | Allows editing and validations, and enables console rendering. -| Mandatory valid examples: ? | Not applicable | Not applicable | Allows validation ++4| Security model: A declaration of which security mechanisms you can used across the APIs. +| OAuth 1.0: The API authentication requires using OAuth 1.0 as described in https://tools.ietf.org/html/rfc5849[RFC5849]. | RAML security schemes | Not applicable | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| OAuth 2.0: The API authentication requires using OAuth 2.0 as described in https://tools.ietf.org/html/rfc6749[RFC6749]. | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| Basic: The API authentication relies on using Basic Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617]. | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| Digest: The API authentication relies on using Digest Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617] | RAML security schemes | Not applicable | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| API Key: The API authentication relies on using API key (either as a header, a cookie parameter, or as a query parameter). | Not applicable | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| Open ID Connect: The API authentication relies on using OAuth2's common flows (implicit, password, client credentials and authorization code) defined in https://tools.ietf.org/html/draft-ietf-oauth-discovery-06[OpenID Connect Discovery]. | Not applicable | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| Pass through: Headers or query parameters are passed through to the API based on a defined mapping. | RAML security schemes | Not applicable | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| Custom: The API authentication relies on another custom authentication method. | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +.4+^.>s| Data description and validation: Validation of any XML or JSON instance against inner elements follows the same restrictions as the validation against a regular XML or JSON schema. +| JSON schema constraints and support: The level of support or constraints on JSON schemas. This is the base for both. RAML Types is a superset | RAML JSON support | OAS Schema object | Allows editing and validations, and enables console rendering. +| Schema Inheritance: The combining and extending of model definitions by using properties of JSON Schema.| RAML type inheritance | *Simulated with `$allOf`, not proper inheritance, murky situation in OAS Schema* | Allows editing and validations, and enables console rendering. +| Type expressions: Type expressions can be used wherever a type is expected. Using type expressions, you can devise type unions, arrays, maps, and other things.| RAML type expressions | Not applicable | Allows editing and validations, and enables console rendering. +| XML Schema constraints and support: The level of support or constraints on XML schemas. | RAML XML support provided indirectly through RAML XML facets for RAML types. | Support provided indirectly through XML properties for the `Schema object` | Limited editing support provided. +| Examples: RAML or OAS examples of implementing validations. | RAML examples | OAS `Example object` | Allows editing and validations, and enables console rendering. +| Mandatory valid examples: Required examples that are valid. | Not applicable | Not applicable | Allows validation +4| Meta-model extensibility: Defines the ability to extend the format to describe additional details or objects. -| Custom property extensions: ? | Annotations | OAS specification extensions | Allows editing and validations, and enables console rendering. -| Custom node extensions: ? | Complex annotations | Not applicable | Allows editing and validations, and enables console rendering. -| Extensions schema: ? | Annotations can have a schema and can be validated |Not applicable | Allows editing and validations, and enables console rendering. -| Extensions semantics: ? | Not applicable | Not applicable | Not applicable +| Custom property extensions: Extensions and additional details for custom properties. | Annotations | OAS specification extensions | Allows editing and validations, and enables console rendering. +| Custom node extensions: Additional details for custom node extensions. | Complex annotations | Not applicable | Allows editing and validations, and enables console rendering. +| Extensions schema: Additional details about extension schemas | Annotations can have a schema and can be validated |Not applicable | Allows editing and validations, and enables console rendering. +| Extensions semantics: Semantics to be used for defining extensions. | Not applicable | Not applicable | Not applicable |=== \ No newline at end of file From cc6eb699dd9552fbf468ad6f65b72092581df7dd Mon Sep 17 00:00:00 2001 From: Priya Ayyar Date: Wed, 31 Mar 2021 13:28:48 -0700 Subject: [PATCH 08/18] DOCS-10035 made edits --- .../ROOT/pages/api-spec-support-api-designer.adoc | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/modules/ROOT/pages/api-spec-support-api-designer.adoc b/modules/ROOT/pages/api-spec-support-api-designer.adoc index f89b908f..e34e84da 100644 --- a/modules/ROOT/pages/api-spec-support-api-designer.adoc +++ b/modules/ROOT/pages/api-spec-support-api-designer.adoc @@ -9,24 +9,24 @@ You can implement your API specification in a way that best suits your needs. Th [%header%autowidth.spread,cols="a,a,a,a"] |=== | Feature: Description| RAML Implementation | OAS Implementation | API Designer Support -+4| Modularity: The ability to break an API specification into reusable and shared units. +4+| *Modularity:* The ability to break an API specification into reusable and shared units. | API Document: The main API specification description metadata, which is the entry point for the specification. | RAML root document | OAS root document | The design of the API project console is rendered and the document and examples are validated. | Libraries: The unit containing collections of related reusable description elements. | RAML library | Can be implemented using an empty OAS specification containing multiple components. | Edited as a stand-alone project. Supports the reuse of the module in an API project. | Fragments: Stand-alone component of the specification that describes a specific element. | RAML fragment | Can be implemented using an empty OAS specification containing a single component.| Edited as a stand-alone project. Supports the reuse of the module in an API project. | Overlays: A partial description of the API specification that you can use to overwrite non-functional aspects of the API specification by composing it with the original specification, for example, translating the documentation to other languages. | RAML overlay | Can be simulated with JSON patch or merge preprocessing. | Can be edited and rendered correctly if used as main the project file. | Extensions: A partial description of the API spec that can be used to overwrite non-functional aspects of the API spec composing it with the original specification, like for example adding the security information for a managed API | RAML extension | Can be simulated with JSON patch or merge preprocessing. | Can be edited and rendered correctly if used as main the project file. -+4| Reusability: The ability to reuse of the API description in multiple specifications. +4+| *Reusability:* The ability to reuse of the API description in multiple specifications. | Inline declarations and references: The ability to declare and reference elements from multiple documents. | Inclusion and named references to: datatypes, traits, resource types, and annotations declarations. | JSON reference and OAS components. | Autocompletion when editing and dedicated rendering provided in the console. | Traits: Macros that extend operations in the functional model, such as pagination, that can be reused in multiple specifications for consistency | Operation macros and RAML traits | Not applicable | Autocompletion when editing and dedicated rendering in console. | Resource types: Macros that extend resources in the functional model with complex behavior and data definition that can be reused in multiple specifications for consistency | Endpoint macros and RAML resource types | Not applicable | Autocompletion when editing and dedicated rendering in console. -+4| API Metadata: Provides metadata about the API that might be used by tooling as required. +4+| *API Metadata:* Provides metadata about the API that might be used by tooling as required. | API Entrypoint: The main entry point for the API description, mostly human-readable information, such as title, version, license, and so forth. | RAML document top level information | OAS Open API object| Can be edited and validated and enables console rendering. | Server and protocols: Denotes the actual connectivity to the service | RAML base URI information | OAS Server object | Small differences in the supported protocols. | Terms of service & licensing: The user agreement and licensing information of the API | Only plain documentation | OAS Info object | | User documentation: Includes user guide and reference material that clarifies how the API works. | RAML description properties in different parts of the specification | OAS description properties in the specification objects | Can be edited and validated and enables console rendering. | Localized documentation: Specifies multi-lingual descriptions | Using overlays | Not applicable | Not applicable | Tags: Classification of parts of the specification | Only use annotations | OAS Tag object | Not applicable -+4| Functional model: A declaration of the resources to use when RPCs are invoked. +4+| *Functional model:* A declaration of the resources to use when RPCs are invoked. | Endpoints: Refers to the resources and RPC invocations in the API | Because RAML is more RESTful, the RAML resources are more explicit in its working and allows for the nesting of those resources. | OAS Path Item objects under the Paths object | Allows editing and validations, and enables console rendering. | Methods and bindings to HTTP uniform interface: Includes operations over the resource and information about how to invoke the RPC operation. | Get, Patch, Put, Post, Delete, Options, and head RAML operations | Get, Put, Post, Delete, Options, Head, Patch, Trace and fixed fields under the OAS Path Item object | Allows editing and validations, and enables console rendering. | Input parameters and HTTP bindings: Specifies the input parameters for the operation. | RAML parameters | OAS Parameter object | Allows editing and validations, and enables console rendering. @@ -34,7 +34,7 @@ You can implement your API specification in a way that best suits your needs. Th | Responses with bindings to HTTP status codes: Specifies the binding to the HTTP status code. | RAML responses | OAS Response object | Allows editing and validations, and enables console rendering. | Callbacks: Specifies the asynchronous invocations and webhooks. | Not applicable | OAS Callback object | Allows editing and validations, and enables console rendering. | Links: Specifies the static connections between endpoints in the specification, excluding hyperlinks in the data. | Not applicable | OAS Link object | Allows editing and validations, and enables console rendering. -+4| Security model: A declaration of which security mechanisms you can used across the APIs. +4+| *Security model:* A declaration of which security mechanisms you can used across the APIs. | OAuth 1.0: The API authentication requires using OAuth 1.0 as described in https://tools.ietf.org/html/rfc5849[RFC5849]. | RAML security schemes | Not applicable | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. | OAuth 2.0: The API authentication requires using OAuth 2.0 as described in https://tools.ietf.org/html/rfc6749[RFC6749]. | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. | Basic: The API authentication relies on using Basic Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617]. | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. @@ -43,14 +43,14 @@ You can implement your API specification in a way that best suits your needs. Th | Open ID Connect: The API authentication relies on using OAuth2's common flows (implicit, password, client credentials and authorization code) defined in https://tools.ietf.org/html/draft-ietf-oauth-discovery-06[OpenID Connect Discovery]. | Not applicable | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. | Pass through: Headers or query parameters are passed through to the API based on a defined mapping. | RAML security schemes | Not applicable | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. | Custom: The API authentication relies on another custom authentication method. | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. -.4+^.>s| Data description and validation: Validation of any XML or JSON instance against inner elements follows the same restrictions as the validation against a regular XML or JSON schema. +4+| *Data description and validation:* Validation of any XML or JSON instance against inner elements follows the same restrictions as the validation against a regular XML or JSON schema. | JSON schema constraints and support: The level of support or constraints on JSON schemas. This is the base for both. RAML Types is a superset | RAML JSON support | OAS Schema object | Allows editing and validations, and enables console rendering. | Schema Inheritance: The combining and extending of model definitions by using properties of JSON Schema.| RAML type inheritance | *Simulated with `$allOf`, not proper inheritance, murky situation in OAS Schema* | Allows editing and validations, and enables console rendering. | Type expressions: Type expressions can be used wherever a type is expected. Using type expressions, you can devise type unions, arrays, maps, and other things.| RAML type expressions | Not applicable | Allows editing and validations, and enables console rendering. | XML Schema constraints and support: The level of support or constraints on XML schemas. | RAML XML support provided indirectly through RAML XML facets for RAML types. | Support provided indirectly through XML properties for the `Schema object` | Limited editing support provided. | Examples: RAML or OAS examples of implementing validations. | RAML examples | OAS `Example object` | Allows editing and validations, and enables console rendering. | Mandatory valid examples: Required examples that are valid. | Not applicable | Not applicable | Allows validation -+4| Meta-model extensibility: Defines the ability to extend the format to describe additional details or objects. +4+| *Meta-model extensibility:* Defines the ability to extend the format to describe additional details or objects. | Custom property extensions: Extensions and additional details for custom properties. | Annotations | OAS specification extensions | Allows editing and validations, and enables console rendering. | Custom node extensions: Additional details for custom node extensions. | Complex annotations | Not applicable | Allows editing and validations, and enables console rendering. | Extensions schema: Additional details about extension schemas | Annotations can have a schema and can be validated |Not applicable | Allows editing and validations, and enables console rendering. From fa9afaca0b9dc049ebf4cfe58cb5c3894cf53dd7 Mon Sep 17 00:00:00 2001 From: Priya Ayyar Date: Thu, 1 Apr 2021 10:53:23 -0700 Subject: [PATCH 09/18] DOCS-10035 made edits --- modules/ROOT/pages/api-spec-support-api-designer.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/api-spec-support-api-designer.adoc b/modules/ROOT/pages/api-spec-support-api-designer.adoc index e34e84da..729a6427 100644 --- a/modules/ROOT/pages/api-spec-support-api-designer.adoc +++ b/modules/ROOT/pages/api-spec-support-api-designer.adoc @@ -15,7 +15,7 @@ You can implement your API specification in a way that best suits your needs. Th | Fragments: Stand-alone component of the specification that describes a specific element. | RAML fragment | Can be implemented using an empty OAS specification containing a single component.| Edited as a stand-alone project. Supports the reuse of the module in an API project. | Overlays: A partial description of the API specification that you can use to overwrite non-functional aspects of the API specification by composing it with the original specification, for example, translating the documentation to other languages. | RAML overlay | Can be simulated with JSON patch or merge preprocessing. | Can be edited and rendered correctly if used as main the project file. | Extensions: A partial description of the API spec that can be used to overwrite non-functional aspects of the API spec composing it with the original specification, like for example adding the security information for a managed API | RAML extension | Can be simulated with JSON patch or merge preprocessing. | Can be edited and rendered correctly if used as main the project file. -4+| *Reusability:* The ability to reuse of the API description in multiple specifications. +4+| *Reusability:* The ability to reuse the API description in multiple specifications. | Inline declarations and references: The ability to declare and reference elements from multiple documents. | Inclusion and named references to: datatypes, traits, resource types, and annotations declarations. | JSON reference and OAS components. | Autocompletion when editing and dedicated rendering provided in the console. | Traits: Macros that extend operations in the functional model, such as pagination, that can be reused in multiple specifications for consistency | Operation macros and RAML traits | Not applicable | Autocompletion when editing and dedicated rendering in console. | Resource types: Macros that extend resources in the functional model with complex behavior and data definition that can be reused in multiple specifications for consistency | Endpoint macros and RAML resource types | Not applicable | Autocompletion when editing and dedicated rendering in console. From c67d8c3bcd7b851f2e78167631aa47bc8462fa67 Mon Sep 17 00:00:00 2001 From: Rodgers-Glenn Date: Thu, 1 Jul 2021 14:54:46 -0500 Subject: [PATCH 10/18] Create api-spec-support-exchange.adoc --- .../ROOT/pages/api-spec-support-exchange.adoc | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 modules/ROOT/pages/api-spec-support-exchange.adoc diff --git a/modules/ROOT/pages/api-spec-support-exchange.adoc b/modules/ROOT/pages/api-spec-support-exchange.adoc new file mode 100644 index 00000000..ab220872 --- /dev/null +++ b/modules/ROOT/pages/api-spec-support-exchange.adoc @@ -0,0 +1,58 @@ += API Specifications Support in API Designer +ifndef::env-site,env-github[] +include::_attributes.adoc[] +endif::[] +:keywords: api, instance, manager + +You can implement your API specification in a way that best suits your needs. The following table explains how each of the features of the API specification is best implemented and the level of support provided for the specification in API Designer. + +[%header%autowidth.spread,cols="a,a,a,a"] +|=== +| Feature: Description| RAML Implementation | OAS Implementation | API Designer Support +4+| *Modularity:* The ability to break an API specification into reusable and shared units. +| API Document: The main API specification description metadata, which is the entry point for the specification. | RAML root document | OAS root document | The design of the API project console is rendered and the document and examples are validated. +| Libraries: The unit containing collections of related reusable description elements. | RAML library | Can be implemented using an empty OAS specification containing multiple components. | Edited as a stand-alone project. Supports the reuse of the module in an API project. +| Fragments: Stand-alone component of the specification that describes a specific element. | RAML fragment | Can be implemented using an empty OAS specification containing a single component.| Edited as a stand-alone project. Supports the reuse of the module in an API project. +| Overlays: A partial description of the API specification that you can use to overwrite non-functional aspects of the API specification by composing it with the original specification, for example, translating the documentation to other languages. | RAML overlay | Can be simulated with JSON patch or merge preprocessing. | Can be edited and rendered correctly if used as main the project file. +| Extensions: A partial description of the API spec that can be used to overwrite non-functional aspects of the API spec composing it with the original specification, like for example adding the security information for a managed API | RAML extension | Can be simulated with JSON patch or merge preprocessing. | Can be edited and rendered correctly if used as main the project file. +4+| *Reusability:* The ability to reuse the API description in multiple specifications. +| Inline declarations and references: The ability to declare and reference elements from multiple documents. | Inclusion and named references to: datatypes, traits, resource types, and annotations declarations. | JSON reference and OAS components. | Autocompletion when editing and dedicated rendering provided in the console. +| Traits: Macros that extend operations in the functional model, such as pagination, that can be reused in multiple specifications for consistency | Operation macros and RAML traits | Not applicable | Autocompletion when editing and dedicated rendering in console. +| Resource types: Macros that extend resources in the functional model with complex behavior and data definition that can be reused in multiple specifications for consistency | Endpoint macros and RAML resource types | Not applicable | Autocompletion when editing and dedicated rendering in console. +4+| *API Metadata:* Provides metadata about the API that might be used by tooling as required. +| API Entrypoint: The main entry point for the API description, mostly human-readable information, such as title, version, license, and so forth. | RAML document top level information | OAS Open API object| Can be edited and validated and enables console rendering. +| Server and protocols: Denotes the actual connectivity to the service | RAML base URI information | OAS Server object | Small differences in the supported protocols. +| Terms of service & licensing: The user agreement and licensing information of the API | Only plain documentation | OAS Info object | +| User documentation: Includes user guide and reference material that clarifies how the API works. | RAML description properties in different parts of the specification | OAS description properties in the specification objects | Can be edited and validated and enables console rendering. +| Localized documentation: Specifies multi-lingual descriptions | Using overlays | Not applicable | Not applicable +| Tags: Classification of parts of the specification | Only use annotations | OAS Tag object | Not applicable +4+| *Functional model:* A declaration of the resources to use when RPCs are invoked. +| Endpoints: Refers to the resources and RPC invocations in the API | Because RAML is more RESTful, the RAML resources are more explicit in its working and allows for the nesting of those resources. | OAS Path Item objects under the Paths object | Allows editing and validations, and enables console rendering. +| Methods and bindings to HTTP uniform interface: Includes operations over the resource and information about how to invoke the RPC operation. | Get, Patch, Put, Post, Delete, Options, and head RAML operations | Get, Put, Post, Delete, Options, Head, Patch, Trace and fixed fields under the OAS Path Item object | Allows editing and validations, and enables console rendering. +| Input parameters and HTTP bindings: Specifies the input parameters for the operation. | RAML parameters | OAS Parameter object | Allows editing and validations, and enables console rendering. +| Responses with multiple media types: Specifies the output parameter for the operation. | RAML responses | OAS Response object | Allows editing and validations, and enables console rendering. +| Responses with bindings to HTTP status codes: Specifies the binding to the HTTP status code. | RAML responses | OAS Response object | Allows editing and validations, and enables console rendering. +| Callbacks: Specifies the asynchronous invocations and webhooks. | Not applicable | OAS Callback object | Allows editing and validations, and enables console rendering. +| Links: Specifies the static connections between endpoints in the specification, excluding hyperlinks in the data. | Not applicable | OAS Link object | Allows editing and validations, and enables console rendering. +4+| *Security model:* A declaration of which security mechanisms you can used across the APIs. +| OAuth 1.0: The API authentication requires using OAuth 1.0 as described in https://tools.ietf.org/html/rfc5849[RFC5849]. | RAML security schemes | Not applicable | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| OAuth 2.0: The API authentication requires using OAuth 2.0 as described in https://tools.ietf.org/html/rfc6749[RFC6749]. | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| Basic: The API authentication relies on using Basic Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617]. | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| Digest: The API authentication relies on using Digest Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617] | RAML security schemes | Not applicable | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| API Key: The API authentication relies on using API key (either as a header, a cookie parameter, or as a query parameter). | Not applicable | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| Open ID Connect: The API authentication relies on using OAuth2's common flows (implicit, password, client credentials and authorization code) defined in https://tools.ietf.org/html/draft-ietf-oauth-discovery-06[OpenID Connect Discovery]. | Not applicable | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| Pass through: Headers or query parameters are passed through to the API based on a defined mapping. | RAML security schemes | Not applicable | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| Custom: The API authentication relies on another custom authentication method. | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +4+| *Data description and validation:* Validation of any XML or JSON instance against inner elements follows the same restrictions as the validation against a regular XML or JSON schema. +| JSON schema constraints and support: The level of support or constraints on JSON schemas. This is the base for both. RAML Types is a superset | RAML JSON support | OAS Schema object | Allows editing and validations, and enables console rendering. +| Schema Inheritance: The combining and extending of model definitions by using properties of JSON Schema.| RAML type inheritance | *Simulated with `$allOf`, not proper inheritance, murky situation in OAS Schema* | Allows editing and validations, and enables console rendering. +| Type expressions: Type expressions can be used wherever a type is expected. Using type expressions, you can devise type unions, arrays, maps, and other things.| RAML type expressions | Not applicable | Allows editing and validations, and enables console rendering. +| XML Schema constraints and support: The level of support or constraints on XML schemas. | RAML XML support provided indirectly through RAML XML facets for RAML types. | Support provided indirectly through XML properties for the `Schema object` | Limited editing support provided. +| Examples: RAML or OAS examples of implementing validations. | RAML examples | OAS `Example object` | Allows editing and validations, and enables console rendering. +| Mandatory valid examples: Required examples that are valid. | Not applicable | Not applicable | Allows validation +4+| *Meta-model extensibility:* Defines the ability to extend the format to describe additional details or objects. +| Custom property extensions: Extensions and additional details for custom properties. | Annotations | OAS specification extensions | Allows editing and validations, and enables console rendering. +| Custom node extensions: Additional details for custom node extensions. | Complex annotations | Not applicable | Allows editing and validations, and enables console rendering. +| Extensions schema: Additional details about extension schemas | Annotations can have a schema and can be validated |Not applicable | Allows editing and validations, and enables console rendering. +| Extensions semantics: Semantics to be used for defining extensions. | Not applicable | Not applicable | Not applicable +|=== From 4f3144b4f289e494ae70cf1ff170ddab6d8339b2 Mon Sep 17 00:00:00 2001 From: Rodgers-Glenn Date: Thu, 1 Jul 2021 15:44:02 -0500 Subject: [PATCH 11/18] Added exchange row and info --- .../ROOT/pages/api-spec-support-exchange.adoc | 80 +++++++++---------- 1 file changed, 40 insertions(+), 40 deletions(-) diff --git a/modules/ROOT/pages/api-spec-support-exchange.adoc b/modules/ROOT/pages/api-spec-support-exchange.adoc index ab220872..f8fb9169 100644 --- a/modules/ROOT/pages/api-spec-support-exchange.adoc +++ b/modules/ROOT/pages/api-spec-support-exchange.adoc @@ -1,4 +1,4 @@ -= API Specifications Support in API Designer += API Specifications Support in Exchange ifndef::env-site,env-github[] include::_attributes.adoc[] endif::[] @@ -8,51 +8,51 @@ You can implement your API specification in a way that best suits your needs. Th [%header%autowidth.spread,cols="a,a,a,a"] |=== -| Feature: Description| RAML Implementation | OAS Implementation | API Designer Support +| Feature: Description| RAML Implementation | OAS Implementation | Exchange Support 4+| *Modularity:* The ability to break an API specification into reusable and shared units. -| API Document: The main API specification description metadata, which is the entry point for the specification. | RAML root document | OAS root document | The design of the API project console is rendered and the document and examples are validated. -| Libraries: The unit containing collections of related reusable description elements. | RAML library | Can be implemented using an empty OAS specification containing multiple components. | Edited as a stand-alone project. Supports the reuse of the module in an API project. -| Fragments: Stand-alone component of the specification that describes a specific element. | RAML fragment | Can be implemented using an empty OAS specification containing a single component.| Edited as a stand-alone project. Supports the reuse of the module in an API project. -| Overlays: A partial description of the API specification that you can use to overwrite non-functional aspects of the API specification by composing it with the original specification, for example, translating the documentation to other languages. | RAML overlay | Can be simulated with JSON patch or merge preprocessing. | Can be edited and rendered correctly if used as main the project file. -| Extensions: A partial description of the API spec that can be used to overwrite non-functional aspects of the API spec composing it with the original specification, like for example adding the security information for a managed API | RAML extension | Can be simulated with JSON patch or merge preprocessing. | Can be edited and rendered correctly if used as main the project file. +| API Document: The main API specification description metadata, which is the entry point for the specification. | RAML root document | OAS root document | Allows publication and versioning of an API asset in Exchange console rendering. +| Libraries: The unit containing collections of related reusable description elements. | RAML library | Can be implemented using an empty OAS specification containing multiple components. | Allows publication of a RAML API fragment asset. +| Fragments: Stand-alone component of the specification that describes a specific element. | RAML fragment | Can be implemented using an empty OAS specification containing a single component.| Allows publication of a RAML API fragment asset. +| Overlays: A partial description of the API specification that you can use to overwrite non-functional aspects of the API specification by composing it with the original specification, for example, translating the documentation to other languages. | RAML overlay | Can be simulated with JSON patch or merge preprocessing. | Modified APIs can be published as an API asset. +| Extensions: A partial description of the API spec that can be used to overwrite non-functional aspects of the API spec composing it with the original specification, like for example adding the security information for a managed API | RAML extension | Can be simulated with JSON patch or merge preprocessing. | Modified APIs can be published as an API asset. 4+| *Reusability:* The ability to reuse the API description in multiple specifications. -| Inline declarations and references: The ability to declare and reference elements from multiple documents. | Inclusion and named references to: datatypes, traits, resource types, and annotations declarations. | JSON reference and OAS components. | Autocompletion when editing and dedicated rendering provided in the console. -| Traits: Macros that extend operations in the functional model, such as pagination, that can be reused in multiple specifications for consistency | Operation macros and RAML traits | Not applicable | Autocompletion when editing and dedicated rendering in console. -| Resource types: Macros that extend resources in the functional model with complex behavior and data definition that can be reused in multiple specifications for consistency | Endpoint macros and RAML resource types | Not applicable | Autocompletion when editing and dedicated rendering in console. +| Inline declarations and references: The ability to declare and reference elements from multiple documents. | Inclusion and named references to: datatypes, traits, resource types, and annotations declarations. | JSON reference and OAS components. | Allows advanced searches when defined in an API document. Does not support advanced searches of fragments. +| Traits: Macros that extend operations in the functional model, such as pagination, that can be reused in multiple specifications for consistency | Operation macros and RAML traits | Not applicable | Allows advanced searches when defined in an API document. Does not support advanced searches of fragments. +| Resource types: Macros that extend resources in the functional model with complex behavior and data definition that can be reused in multiple specifications for consistency | Endpoint macros and RAML resource types | Not applicable | Allows advanced searches when defined in an API document. Does not support advanced searches of fragments. 4+| *API Metadata:* Provides metadata about the API that might be used by tooling as required. -| API Entrypoint: The main entry point for the API description, mostly human-readable information, such as title, version, license, and so forth. | RAML document top level information | OAS Open API object| Can be edited and validated and enables console rendering. -| Server and protocols: Denotes the actual connectivity to the service | RAML base URI information | OAS Server object | Small differences in the supported protocols. -| Terms of service & licensing: The user agreement and licensing information of the API | Only plain documentation | OAS Info object | -| User documentation: Includes user guide and reference material that clarifies how the API works. | RAML description properties in different parts of the specification | OAS description properties in the specification objects | Can be edited and validated and enables console rendering. -| Localized documentation: Specifies multi-lingual descriptions | Using overlays | Not applicable | Not applicable -| Tags: Classification of parts of the specification | Only use annotations | OAS Tag object | Not applicable +| API Entrypoint: The main entry point for the API description, mostly human-readable information, such as title, version, license, and so forth. | RAML document top level information | OAS Open API object| Enables console rendering and default values for asset creation. +| Server and protocols: Denotes the actual connectivity to the service | RAML base URI information | OAS Server object | Enables console rendering and default values for lists of instances. +| Terms of service & licensing: The user agreement and licensing information of the API | Only plain documentation | OAS Info object | Allows advanced searches and enables console documentation. +| User documentation: Includes user guide and reference material that clarifies how the API works. | RAML description properties in different parts of the specification | OAS description properties in the specification objects | Allows advanced searches of API documents and enables console documentation. +| Localized documentation: Specifies multi-lingual descriptions | Using overlays | Not applicable | Allows advanced searches and enables console documentation. +| Tags: Classification of parts of the specification | Only use annotations | OAS Tag object | Allows advanced searches and enables console documentation. 4+| *Functional model:* A declaration of the resources to use when RPCs are invoked. -| Endpoints: Refers to the resources and RPC invocations in the API | Because RAML is more RESTful, the RAML resources are more explicit in its working and allows for the nesting of those resources. | OAS Path Item objects under the Paths object | Allows editing and validations, and enables console rendering. -| Methods and bindings to HTTP uniform interface: Includes operations over the resource and information about how to invoke the RPC operation. | Get, Patch, Put, Post, Delete, Options, and head RAML operations | Get, Put, Post, Delete, Options, Head, Patch, Trace and fixed fields under the OAS Path Item object | Allows editing and validations, and enables console rendering. -| Input parameters and HTTP bindings: Specifies the input parameters for the operation. | RAML parameters | OAS Parameter object | Allows editing and validations, and enables console rendering. -| Responses with multiple media types: Specifies the output parameter for the operation. | RAML responses | OAS Response object | Allows editing and validations, and enables console rendering. -| Responses with bindings to HTTP status codes: Specifies the binding to the HTTP status code. | RAML responses | OAS Response object | Allows editing and validations, and enables console rendering. -| Callbacks: Specifies the asynchronous invocations and webhooks. | Not applicable | OAS Callback object | Allows editing and validations, and enables console rendering. -| Links: Specifies the static connections between endpoints in the specification, excluding hyperlinks in the data. | Not applicable | OAS Link object | Allows editing and validations, and enables console rendering. +| Endpoints: Refers to the resources and RPC invocations in the API | Because RAML is more RESTful, the RAML resources are more explicit in its working and allows for the nesting of those resources. | OAS Path Item objects under the Paths object | Enables console rendering. +| Methods and bindings to HTTP uniform interface: Includes operations over the resource and information about how to invoke the RPC operation. | Get, Patch, Put, Post, Delete, Options, and head RAML operations | Get, Put, Post, Delete, Options, Head, Patch, Trace and fixed fields under the OAS Path Item object | Enables console rendering. +| Input parameters and HTTP bindings: Specifies the input parameters for the operation. | RAML parameters | OAS Parameter object | Enables console rendering. +| Responses with multiple media types: Specifies the output parameter for the operation. | RAML responses | OAS Response object | Enables console rendering. +| Responses with bindings to HTTP status codes: Specifies the binding to the HTTP status code. | RAML responses | OAS Response object | Enables console rendering. +| Callbacks: Specifies the asynchronous invocations and webhooks. | Not applicable | OAS Callback object | Enables console rendering. +| Links: Specifies the static connections between endpoints in the specification, excluding hyperlinks in the data. | Not applicable | OAS Link object | Enables console rendering. 4+| *Security model:* A declaration of which security mechanisms you can used across the APIs. -| OAuth 1.0: The API authentication requires using OAuth 1.0 as described in https://tools.ietf.org/html/rfc5849[RFC5849]. | RAML security schemes | Not applicable | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. -| OAuth 2.0: The API authentication requires using OAuth 2.0 as described in https://tools.ietf.org/html/rfc6749[RFC6749]. | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. -| Basic: The API authentication relies on using Basic Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617]. | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. -| Digest: The API authentication relies on using Digest Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617] | RAML security schemes | Not applicable | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. -| API Key: The API authentication relies on using API key (either as a header, a cookie parameter, or as a query parameter). | Not applicable | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. -| Open ID Connect: The API authentication relies on using OAuth2's common flows (implicit, password, client credentials and authorization code) defined in https://tools.ietf.org/html/draft-ietf-oauth-discovery-06[OpenID Connect Discovery]. | Not applicable | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. -| Pass through: Headers or query parameters are passed through to the API based on a defined mapping. | RAML security schemes | Not applicable | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. -| Custom: The API authentication relies on another custom authentication method. | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| OAuth 1.0: The API authentication requires using OAuth 1.0 as described in https://tools.ietf.org/html/rfc5849[RFC5849]. | RAML security schemes | Not applicable | Allows advanced searches and enables console rendering. +| OAuth 2.0: The API authentication requires using OAuth 2.0 as described in https://tools.ietf.org/html/rfc6749[RFC6749]. | RAML security schemes | OAS Security Scheme object | Allows advanced searches and enables console rendering. +| Basic: The API authentication relies on using Basic Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617]. | RAML security schemes | OAS Security Scheme object | Allows advanced searches and enables console rendering. +| Digest: The API authentication relies on using Digest Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617] | RAML security schemes | Not applicable | Allows advanced searches and enables console rendering. +| API Key: The API authentication relies on using API key (either as a header, a cookie parameter, or as a query parameter). | Not applicable | OAS Security Scheme object | Allows advanced searches and enables console rendering. +| Open ID Connect: The API authentication relies on using OAuth2's common flows (implicit, password, client credentials and authorization code) defined in https://tools.ietf.org/html/draft-ietf-oauth-discovery-06[OpenID Connect Discovery]. | Not applicable | OAS Security Scheme object | Allows advanced searches and enables console rendering. +| Pass through: Headers or query parameters are passed through to the API based on a defined mapping. | RAML security schemes | Not applicable | Allows advanced searches and enables console rendering. +| Custom: The API authentication relies on another custom authentication method. | RAML security schemes | OAS Security Scheme object | Allows advanced searches and enables console rendering. 4+| *Data description and validation:* Validation of any XML or JSON instance against inner elements follows the same restrictions as the validation against a regular XML or JSON schema. -| JSON schema constraints and support: The level of support or constraints on JSON schemas. This is the base for both. RAML Types is a superset | RAML JSON support | OAS Schema object | Allows editing and validations, and enables console rendering. -| Schema Inheritance: The combining and extending of model definitions by using properties of JSON Schema.| RAML type inheritance | *Simulated with `$allOf`, not proper inheritance, murky situation in OAS Schema* | Allows editing and validations, and enables console rendering. -| Type expressions: Type expressions can be used wherever a type is expected. Using type expressions, you can devise type unions, arrays, maps, and other things.| RAML type expressions | Not applicable | Allows editing and validations, and enables console rendering. -| XML Schema constraints and support: The level of support or constraints on XML schemas. | RAML XML support provided indirectly through RAML XML facets for RAML types. | Support provided indirectly through XML properties for the `Schema object` | Limited editing support provided. -| Examples: RAML or OAS examples of implementing validations. | RAML examples | OAS `Example object` | Allows editing and validations, and enables console rendering. -| Mandatory valid examples: Required examples that are valid. | Not applicable | Not applicable | Allows validation +| JSON schema constraints and support: The level of support or constraints on JSON schemas. This is the base for both. RAML Types is a superset | RAML JSON support | OAS Schema object | Allows advanced searches in the main API document and enables console rendering. Does not support validation of directly uploaded specs. +| Schema Inheritance: The combining and extending of model definitions by using properties of JSON Schema.| RAML type inheritance | *Simulated with `$allOf`, not proper inheritance, murky situation in OAS Schema* | Allows advanced searches and enables console rendering. +| Type expressions: Type expressions can be used wherever a type is expected. Using type expressions, you can devise type unions, arrays, maps, and other things.| RAML type expressions | Not applicable | Allows advanced searches of types in the expression and enables console rendering. +| XML Schema constraints and support: The level of support or constraints on XML schemas. | RAML XML support provided indirectly through RAML XML facets for RAML types. | Support provided indirectly through XML properties for the `Schema object` | Enables console rendering. +| Examples: RAML or OAS examples of implementing validations. | RAML examples | OAS `Example object` | Allows advanced searches and enables console rendering. +| Mandatory valid examples: Required examples that are valid. | Not applicable | Not applicable | Does not support validation of directly uploaded specs. 4+| *Meta-model extensibility:* Defines the ability to extend the format to describe additional details or objects. -| Custom property extensions: Extensions and additional details for custom properties. | Annotations | OAS specification extensions | Allows editing and validations, and enables console rendering. -| Custom node extensions: Additional details for custom node extensions. | Complex annotations | Not applicable | Allows editing and validations, and enables console rendering. -| Extensions schema: Additional details about extension schemas | Annotations can have a schema and can be validated |Not applicable | Allows editing and validations, and enables console rendering. +| Custom property extensions: Extensions and additional details for custom properties. | Annotations | OAS specification extensions | Allows advanced searches and enables console rendering. +| Custom node extensions: Additional details for custom node extensions. | Complex annotations | Not applicable | Allows advanced searches and enables console rendering. +| Extensions schema: Additional details about extension schemas | Annotations can have a schema and can be validated |Not applicable | Allows advanced searches and enables console rendering. | Extensions semantics: Semantics to be used for defining extensions. | Not applicable | Not applicable | Not applicable |=== From 021e8460ff8f654ff55ef14e4999cbb742059784 Mon Sep 17 00:00:00 2001 From: Rodgers-Glenn Date: Thu, 8 Jul 2021 10:24:20 -0400 Subject: [PATCH 12/18] Updated anypoint exchange specs per Priya's comments. --- modules/ROOT/pages/api-spec-support-exchange.adoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/modules/ROOT/pages/api-spec-support-exchange.adoc b/modules/ROOT/pages/api-spec-support-exchange.adoc index f8fb9169..1c14d985 100644 --- a/modules/ROOT/pages/api-spec-support-exchange.adoc +++ b/modules/ROOT/pages/api-spec-support-exchange.adoc @@ -4,17 +4,17 @@ include::_attributes.adoc[] endif::[] :keywords: api, instance, manager -You can implement your API specification in a way that best suits your needs. The following table explains how each of the features of the API specification is best implemented and the level of support provided for the specification in API Designer. +You can implement your API specification in a way that best suits your needs. The following table explains how each of the features of the API specification is best implemented and the level of support provided for the specification in Anypoint Exchange. [%header%autowidth.spread,cols="a,a,a,a"] |=== | Feature: Description| RAML Implementation | OAS Implementation | Exchange Support 4+| *Modularity:* The ability to break an API specification into reusable and shared units. -| API Document: The main API specification description metadata, which is the entry point for the specification. | RAML root document | OAS root document | Allows publication and versioning of an API asset in Exchange console rendering. -| Libraries: The unit containing collections of related reusable description elements. | RAML library | Can be implemented using an empty OAS specification containing multiple components. | Allows publication of a RAML API fragment asset. -| Fragments: Stand-alone component of the specification that describes a specific element. | RAML fragment | Can be implemented using an empty OAS specification containing a single component.| Allows publication of a RAML API fragment asset. -| Overlays: A partial description of the API specification that you can use to overwrite non-functional aspects of the API specification by composing it with the original specification, for example, translating the documentation to other languages. | RAML overlay | Can be simulated with JSON patch or merge preprocessing. | Modified APIs can be published as an API asset. -| Extensions: A partial description of the API spec that can be used to overwrite non-functional aspects of the API spec composing it with the original specification, like for example adding the security information for a managed API | RAML extension | Can be simulated with JSON patch or merge preprocessing. | Modified APIs can be published as an API asset. +| API Document: The main API specification description metadata, which is the entry point for the specification. | RAML root document | OAS root document | Allows publication and versioning of an API asset in Exchange console rendering. Additionally, advanced search is supported. +| Libraries: The unit containing collections of related reusable description elements. | RAML library | Can be implemented using an empty OAS specification containing multiple components. | Allows publication of a RAML API fragment asset (only RAML). Console rendering and advanced search are not supported. +| Fragments: Stand-alone component of the specification that describes a specific element. | RAML fragment | Can be implemented using an empty OAS specification containing a single component.| Allows publication of a RAML API fragment asset (only RAML). Console rendering and advanced search are not supported. +| Overlays: A partial description of the API specification that you can use to overwrite non-functional aspects of the API specification by composing it with the original specification, for example, translating the documentation to other languages. | RAML overlay | Can be simulated with JSON patch or merge preprocessing. | Allows publishing modified APIs as an API asset. +| Extensions: A partial description of the API spec that can be used to overwrite non-functional aspects of the API spec composing it with the original specification, like for example adding the security information for a managed API | RAML extension | Can be simulated with JSON patch or merge preprocessing. | Allows publishing modified APIs as an API asset. 4+| *Reusability:* The ability to reuse the API description in multiple specifications. | Inline declarations and references: The ability to declare and reference elements from multiple documents. | Inclusion and named references to: datatypes, traits, resource types, and annotations declarations. | JSON reference and OAS components. | Allows advanced searches when defined in an API document. Does not support advanced searches of fragments. | Traits: Macros that extend operations in the functional model, such as pagination, that can be reused in multiple specifications for consistency | Operation macros and RAML traits | Not applicable | Allows advanced searches when defined in an API document. Does not support advanced searches of fragments. From 075dd9e12c82cbca13e04912ebfac71f9931b9f2 Mon Sep 17 00:00:00 2001 From: Rodgers-Glenn Date: Thu, 8 Jul 2021 10:52:52 -0400 Subject: [PATCH 13/18] Added API-Manager-Specs --- .../pages/api-spec-support-api-manager.adoc | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 modules/ROOT/pages/api-spec-support-api-manager.adoc diff --git a/modules/ROOT/pages/api-spec-support-api-manager.adoc b/modules/ROOT/pages/api-spec-support-api-manager.adoc new file mode 100644 index 00000000..00aaf5b0 --- /dev/null +++ b/modules/ROOT/pages/api-spec-support-api-manager.adoc @@ -0,0 +1,58 @@ += API Specifications Support in API Manager +ifndef::env-site,env-github[] +include::_attributes.adoc[] +endif::[] +:keywords: api, instance, manager + +You can implement your API specification in a way that best suits your needs. The following table explains how each of the features of the API specification is best implemented and the level of support provided for the specification in API Manager. + +[%header%autowidth.spread,cols="a,a,a,a"] +|=== +| Feature: Description| RAML Implementation | OAS Implementation | API Manager Support +4+| *Modularity:* The ability to break an API specification into reusable and shared units. +| API Document: The main API specification description metadata, which is the entry point for the specification. | RAML root document | OAS root document | Manages the API instance associated with the API (RAML only). +| Libraries: The unit containing collections of related reusable description elements. | RAML library | Can be implemented using an empty OAS specification containing multiple components. | Not applicable +| Fragments: Stand-alone component of the specification that describes a specific element. | RAML fragment | Can be implemented using an empty OAS specification containing a single component.| Not applicable +| Overlays: A partial description of the API specification that you can use to overwrite non-functional aspects of the API specification by composing it with the original specification, for example, translating the documentation to other languages. | RAML overlay | Can be simulated with JSON patch or merge preprocessing. | Manages modified APIs. +| Extensions: A partial description of the API spec that can be used to overwrite non-functional aspects of the API spec composing it with the original specification, like for example adding the security information for a managed API | RAML extension | Can be simulated with JSON patch or merge preprocessing. | Manages modified APIs. +4+| *Reusability:* The ability to reuse the API description in multiple specifications. +| Inline declarations and references: The ability to declare and reference elements from multiple documents. | Inclusion and named references to: datatypes, traits, resource types, and annotations declarations. | JSON reference and OAS components. | Inlines through AMF for management. +| Traits: Macros that extend operations in the functional model, such as pagination, that can be reused in multiple specifications for consistency | Operation macros and RAML traits | Not applicable | Inlines through AMF for management. +| Resource types: Macros that extend resources in the functional model with complex behavior and data definition that can be reused in multiple specifications for consistency | Endpoint macros and RAML resource types | Not applicable | Inlines through AMF for management. +4+| *API Metadata:* Provides metadata about the API that might be used by tooling as required. +| API Entrypoint: The main entry point for the API description, mostly human-readable information, such as title, version, license, and so forth. | RAML document top level information | OAS Open API object| Provides default values for asset creation. +| Server and protocols: Denotes the actual connectivity to the service | RAML base URI information | OAS Server object | API Manager overwrites the instance being deployed and managed. +| Terms of service & licensing: The user agreement and licensing information of the API | Only plain documentation | OAS Info object | Not applicable +| User documentation: Includes user guide and reference material that clarifies how the API works. | RAML description properties in different parts of the specification | OAS description properties in the specification objects | Not applicable +| Localized documentation: Specifies multi-lingual descriptions | Using overlays | Not applicable | Not applicable +| Tags: Classification of parts of the specification | Only use annotations | OAS Tag object | Not applicable +4+| *Functional model:* A declaration of the resources to use when RPCs are invoked. +| Endpoints: Refers to the resources and RPC invocations in the API | Because RAML is more RESTful, the RAML resources are more explicit in its working and allows for the nesting of those resources. | OAS Path Item objects under the Paths object | Applies endpoint level policies (RAML only). +| Methods and bindings to HTTP uniform interface: Includes operations over the resource and information about how to invoke the RPC operation. | Get, Patch, Put, Post, Delete, Options, and head RAML operations | Get, Put, Post, Delete, Options, Head, Patch, Trace and fixed fields under the OAS Path Item object | Applies endpoint level policies (RAML only). +| Input parameters and HTTP bindings: Specifies the input parameters for the operation. | RAML parameters | OAS Parameter object | Applies endpoint level policies (RAML only). +| Responses with multiple media types: Specifies the output parameter for the operation. | RAML responses | OAS Response object | Applies endpoint level policies (RAML only). +| Responses with bindings to HTTP status codes: Specifies the binding to the HTTP status code. | RAML responses | OAS Response object | Applies endpoint level policies (RAML only). +| Callbacks: Specifies the asynchronous invocations and webhooks. | Not applicable | OAS Callback object | Not applicable +| Links: Specifies the static connections between endpoints in the specification, excluding hyperlinks in the data. | Not applicable | OAS Link object | Not applicable +4+| *Security model:* A declaration of which security mechanisms you can used across the APIs. +| OAuth 1.0: The API authentication requires using OAuth 1.0 as described in https://tools.ietf.org/html/rfc5849[RFC5849]. | RAML security schemes | Not applicable | Not applicable +| OAuth 2.0: The API authentication requires using OAuth 2.0 as described in https://tools.ietf.org/html/rfc6749[RFC6749]. | RAML security schemes | OAS Security Scheme object | Can apply as a policy. +| Basic: The API authentication relies on using Basic Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617]. | RAML security schemes | OAS Security Scheme object | Can apply as a policy. +| Digest: The API authentication relies on using Digest Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617] | RAML security schemes | Not applicable | Not applicable +| API Key: The API authentication relies on using API key (either as a header, a cookie parameter, or as a query parameter). | Not applicable | OAS Security Scheme object | Can apply as a policy. +| Open ID Connect: The API authentication relies on using OAuth2's common flows (implicit, password, client credentials and authorization code) defined in https://tools.ietf.org/html/draft-ietf-oauth-discovery-06[OpenID Connect Discovery]. | Not applicable | OAS Security Scheme object | Can apply as a policy. +| Pass through: Headers or query parameters are passed through to the API based on a defined mapping. | RAML security schemes | Not applicable | Does not need policy. +| Custom: The API authentication relies on another custom authentication method. | RAML security schemes | OAS Security Scheme object | Can implement a custom policy. +4+| *Data description and validation:* Validation of any XML or JSON instance against inner elements follows the same restrictions as the validation against a regular XML or JSON schema. +| JSON schema constraints and support: The level of support or constraints on JSON schemas. This is the base for both. RAML Types is a superset | RAML JSON support | OAS Schema object | Not applicable +| Schema Inheritance: The combining and extending of model definitions by using properties of JSON Schema.| RAML type inheritance | *Simulated with `$allOf`, not proper inheritance, murky situation in OAS Schema* | Not applicable +| Type expressions: Type expressions can be used wherever a type is expected. Using type expressions, you can devise type unions, arrays, maps, and other things.| RAML type expressions | Not applicable | Not applicable +| XML Schema constraints and support: The level of support or constraints on XML schemas. | RAML XML support provided indirectly through RAML XML facets for RAML types. | Support provided indirectly through XML properties for the `Schema object` | Not applicable +| Examples: RAML or OAS examples of implementing validations. | RAML examples | OAS `Example object` | Not applicable +| Mandatory valid examples: Required examples that are valid. | Not applicable | Not applicable | Not applicable +4+| *Meta-model extensibility:* Defines the ability to extend the format to describe additional details or objects. +| Custom property extensions: Extensions and additional details for custom properties. | Annotations | OAS specification extensions | Not applicable +| Custom node extensions: Additional details for custom node extensions. | Complex annotations | Not applicable | Not applicable +| Extensions schema: Additional details about extension schemas | Annotations can have a schema and can be validated |Not applicable | Not applicable +| Extensions semantics: Semantics to be used for defining extensions. | Not applicable | Not applicable | Not applicable +|=== From fec77d582295b332b552c6458e4046ea741257f4 Mon Sep 17 00:00:00 2001 From: Rodgers-Glenn Date: Thu, 8 Jul 2021 13:33:40 -0400 Subject: [PATCH 14/18] Added api-specs-datagragh also fixed a few typos in other spec pages --- .../pages/api-spec-support-api-designer.adoc | 28 ++++----- .../pages/api-spec-support-api-manager.adoc | 2 +- .../pages/api-spec-support-datagraph.adoc | 58 +++++++++++++++++++ .../ROOT/pages/api-spec-support-exchange.adoc | 4 +- 4 files changed, 75 insertions(+), 17 deletions(-) create mode 100644 modules/ROOT/pages/api-spec-support-datagraph.adoc diff --git a/modules/ROOT/pages/api-spec-support-api-designer.adoc b/modules/ROOT/pages/api-spec-support-api-designer.adoc index 729a6427..b59e13f7 100644 --- a/modules/ROOT/pages/api-spec-support-api-designer.adoc +++ b/modules/ROOT/pages/api-spec-support-api-designer.adoc @@ -8,11 +8,11 @@ You can implement your API specification in a way that best suits your needs. Th [%header%autowidth.spread,cols="a,a,a,a"] |=== -| Feature: Description| RAML Implementation | OAS Implementation | API Designer Support +| Feature: Description| RAML Implementation | OAS Implementation | API Designer Support 4+| *Modularity:* The ability to break an API specification into reusable and shared units. -| API Document: The main API specification description metadata, which is the entry point for the specification. | RAML root document | OAS root document | The design of the API project console is rendered and the document and examples are validated. +| API Document: The main API specification description metadata, which is the entry point for the specification. | RAML root document | OAS root document | The design of the API project console is rendered and the document and examples are validated. | Libraries: The unit containing collections of related reusable description elements. | RAML library | Can be implemented using an empty OAS specification containing multiple components. | Edited as a stand-alone project. Supports the reuse of the module in an API project. -| Fragments: Stand-alone component of the specification that describes a specific element. | RAML fragment | Can be implemented using an empty OAS specification containing a single component.| Edited as a stand-alone project. Supports the reuse of the module in an API project. +| Fragments: Stand-alone component of the specification that describes a specific element. | RAML fragment | Can be implemented using an empty OAS specification containing a single component.| Edited as a stand-alone project. Supports the reuse of the module in an API project. | Overlays: A partial description of the API specification that you can use to overwrite non-functional aspects of the API specification by composing it with the original specification, for example, translating the documentation to other languages. | RAML overlay | Can be simulated with JSON patch or merge preprocessing. | Can be edited and rendered correctly if used as main the project file. | Extensions: A partial description of the API spec that can be used to overwrite non-functional aspects of the API spec composing it with the original specification, like for example adding the security information for a managed API | RAML extension | Can be simulated with JSON patch or merge preprocessing. | Can be edited and rendered correctly if used as main the project file. 4+| *Reusability:* The ability to reuse the API description in multiple specifications. @@ -22,9 +22,9 @@ You can implement your API specification in a way that best suits your needs. Th 4+| *API Metadata:* Provides metadata about the API that might be used by tooling as required. | API Entrypoint: The main entry point for the API description, mostly human-readable information, such as title, version, license, and so forth. | RAML document top level information | OAS Open API object| Can be edited and validated and enables console rendering. | Server and protocols: Denotes the actual connectivity to the service | RAML base URI information | OAS Server object | Small differences in the supported protocols. -| Terms of service & licensing: The user agreement and licensing information of the API | Only plain documentation | OAS Info object | +| Terms of service & licensing: The user agreement and licensing information of the API | Only plain documentation | OAS Info object | | User documentation: Includes user guide and reference material that clarifies how the API works. | RAML description properties in different parts of the specification | OAS description properties in the specification objects | Can be edited and validated and enables console rendering. -| Localized documentation: Specifies multi-lingual descriptions | Using overlays | Not applicable | Not applicable +| Localized documentation: Specifies multi-lingual descriptions | Using overlays | Not applicable | Not applicable | Tags: Classification of parts of the specification | Only use annotations | OAS Tag object | Not applicable 4+| *Functional model:* A declaration of the resources to use when RPCs are invoked. | Endpoints: Refers to the resources and RPC invocations in the API | Because RAML is more RESTful, the RAML resources are more explicit in its working and allows for the nesting of those resources. | OAS Path Item objects under the Paths object | Allows editing and validations, and enables console rendering. @@ -35,24 +35,24 @@ You can implement your API specification in a way that best suits your needs. Th | Callbacks: Specifies the asynchronous invocations and webhooks. | Not applicable | OAS Callback object | Allows editing and validations, and enables console rendering. | Links: Specifies the static connections between endpoints in the specification, excluding hyperlinks in the data. | Not applicable | OAS Link object | Allows editing and validations, and enables console rendering. 4+| *Security model:* A declaration of which security mechanisms you can used across the APIs. -| OAuth 1.0: The API authentication requires using OAuth 1.0 as described in https://tools.ietf.org/html/rfc5849[RFC5849]. | RAML security schemes | Not applicable | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. -| OAuth 2.0: The API authentication requires using OAuth 2.0 as described in https://tools.ietf.org/html/rfc6749[RFC6749]. | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. -| Basic: The API authentication relies on using Basic Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617]. | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. -| Digest: The API authentication relies on using Digest Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617] | RAML security schemes | Not applicable | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| OAuth 1.0: The API authentication requires using OAuth 1.0 as described in https://tools.ietf.org/html/rfc5849[RFC5849]. | RAML security schemes | Not applicable | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| OAuth 2.0: The API authentication requires using OAuth 2.0 as described in https://tools.ietf.org/html/rfc6749[RFC6749]. | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| Basic: The API authentication relies on using Basic Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617]. | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| Digest: The API authentication relies on using Digest Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617] | RAML security schemes | Not applicable | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. | API Key: The API authentication relies on using API key (either as a header, a cookie parameter, or as a query parameter). | Not applicable | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. -| Open ID Connect: The API authentication relies on using OAuth2's common flows (implicit, password, client credentials and authorization code) defined in https://tools.ietf.org/html/draft-ietf-oauth-discovery-06[OpenID Connect Discovery]. | Not applicable | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| Open ID Connect: The API authentication relies on using OAuth2's common flows (implicit, password, client credentials and authorization code) defined in https://tools.ietf.org/html/draft-ietf-oauth-discovery-06[OpenID Connect Discovery]. | Not applicable | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. | Pass through: Headers or query parameters are passed through to the API based on a defined mapping. | RAML security schemes | Not applicable | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. | Custom: The API authentication relies on another custom authentication method. | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. 4+| *Data description and validation:* Validation of any XML or JSON instance against inner elements follows the same restrictions as the validation against a regular XML or JSON schema. | JSON schema constraints and support: The level of support or constraints on JSON schemas. This is the base for both. RAML Types is a superset | RAML JSON support | OAS Schema object | Allows editing and validations, and enables console rendering. | Schema Inheritance: The combining and extending of model definitions by using properties of JSON Schema.| RAML type inheritance | *Simulated with `$allOf`, not proper inheritance, murky situation in OAS Schema* | Allows editing and validations, and enables console rendering. -| Type expressions: Type expressions can be used wherever a type is expected. Using type expressions, you can devise type unions, arrays, maps, and other things.| RAML type expressions | Not applicable | Allows editing and validations, and enables console rendering. +| Type expressions: Type expressions can be used wherever a type is expected. Using type expressions, you can devise type unions, arrays, maps, and other things.| RAML type expressions | Not applicable | Allows editing and validations, and enables console rendering. | XML Schema constraints and support: The level of support or constraints on XML schemas. | RAML XML support provided indirectly through RAML XML facets for RAML types. | Support provided indirectly through XML properties for the `Schema object` | Limited editing support provided. | Examples: RAML or OAS examples of implementing validations. | RAML examples | OAS `Example object` | Allows editing and validations, and enables console rendering. | Mandatory valid examples: Required examples that are valid. | Not applicable | Not applicable | Allows validation 4+| *Meta-model extensibility:* Defines the ability to extend the format to describe additional details or objects. | Custom property extensions: Extensions and additional details for custom properties. | Annotations | OAS specification extensions | Allows editing and validations, and enables console rendering. | Custom node extensions: Additional details for custom node extensions. | Complex annotations | Not applicable | Allows editing and validations, and enables console rendering. -| Extensions schema: Additional details about extension schemas | Annotations can have a schema and can be validated |Not applicable | Allows editing and validations, and enables console rendering. -| Extensions semantics: Semantics to be used for defining extensions. | Not applicable | Not applicable | Not applicable -|=== \ No newline at end of file +| Extensions schema: Additional details about extension schemas | Annotations can have a schema and can be validated | Not applicable | Allows editing and validations, and enables console rendering. +| Extensions semantics: Semantics to be used for defining extensions. | Not applicable | Not applicable | Not applicable +|=== diff --git a/modules/ROOT/pages/api-spec-support-api-manager.adoc b/modules/ROOT/pages/api-spec-support-api-manager.adoc index 00aaf5b0..e830a091 100644 --- a/modules/ROOT/pages/api-spec-support-api-manager.adoc +++ b/modules/ROOT/pages/api-spec-support-api-manager.adoc @@ -1,4 +1,4 @@ -= API Specifications Support in API Manager += API Specifications Support in Anypoint API Manager ifndef::env-site,env-github[] include::_attributes.adoc[] endif::[] diff --git a/modules/ROOT/pages/api-spec-support-datagraph.adoc b/modules/ROOT/pages/api-spec-support-datagraph.adoc new file mode 100644 index 00000000..4fb31dea --- /dev/null +++ b/modules/ROOT/pages/api-spec-support-datagraph.adoc @@ -0,0 +1,58 @@ += API Specifications Support in Anypoint Datagraph +ifndef::env-site,env-github[] +include::_attributes.adoc[] +endif::[] +:keywords: api, instance, manager + +You can implement your API specification in a way that best suits your needs. The following table explains how each of the features of the API specification is best implemented and the level of support provided for the specification in Anypoint Datagraph. + +[%header%autowidth.spread,cols="a,a,a,a"] +|=== +| Feature: Description| RAML Implementation | OAS Implementation | Anypoint Datagraph Support +4+| *Modularity:* The ability to break an API specification into reusable and shared units. +| API Document: The main API specification description metadata, which is the entry point for the specification. | RAML root document | OAS root document | Can be federated as part of a federated API. +| Libraries: The unit containing collections of related reusable description elements. | RAML library | Can be implemented using an empty OAS specification containing multiple components. | Not applicable +| Fragments: Stand-alone component of the specification that describes a specific element. | RAML fragment | Can be implemented using an empty OAS specification containing a single component.| Not applicable +| Overlays: A partial description of the API specification that you can use to overwrite non-functional aspects of the API specification by composing it with the original specification, for example, translating the documentation to other languages. | RAML overlay | Can be simulated with JSON patch or merge preprocessing. | Modified APIs can be federated. +| Extensions: A partial description of the API spec that can be used to overwrite non-functional aspects of the API spec composing it with the original specification, like for example adding the security information for a managed API | RAML extension | Can be simulated with JSON patch or merge preprocessing. | Modified APIs can be federated. +4+| *Reusability:* The ability to reuse the API description in multiple specifications. +| Inline declarations and references: The ability to declare and reference elements from multiple documents. | Inclusion and named references to: datatypes, traits, resource types, and annotations declarations. | JSON reference and OAS components. | Provides data type names for federated APIs. +| Traits: Macros that extend operations in the functional model, such as pagination, that can be reused in multiple specifications for consistency | Operation macros and RAML traits | Not applicable | Inlines through AMF for federation. +| Resource types: Macros that extend resources in the functional model with complex behavior and data definition that can be reused in multiple specifications for consistency | Endpoint macros and RAML resource types | Not applicable | Inlines through AMF for federation. +4+| *API Metadata:* Provides metadata about the API that might be used by tooling as required. +| API Entrypoint: The main entry point for the API description, mostly human-readable information, such as title, version, license, and so forth. | RAML document top level information | OAS Open API object| Provides default values for APIs being federated. +| Server and protocols: Denotes the actual connectivity to the service | RAML base URI information | OAS Server object | Provides default values for external APIs not managed by Anypoint Platform. +| Terms of service & licensing: The user agreement and licensing information of the API | Only plain documentation | OAS Info object | Not applicable +| User documentation: Includes user guide and reference material that clarifies how the API works. | RAML description properties in different parts of the specification | OAS description properties in the specification objects | Not applicable +| Localized documentation: Specifies multi-lingual descriptions | Using overlays | Not applicable | Not applicable +| Tags: Classification of parts of the specification | Only use annotations | OAS Tag object | Not applicable +4+| *Functional model:* A declaration of the resources to use when RPCs are invoked. +| Endpoints: Refers to the resources and RPC invocations in the API | Because RAML is more RESTful, the RAML resources are more explicit in its working and allows for the nesting of those resources. | OAS Path Item objects under the Paths object | Generates data type providers for federation. +| Methods and bindings to HTTP uniform interface: Includes operations over the resource and information about how to invoke the RPC operation. | Get, Patch, Put, Post, Delete, Options, and head RAML operations | Get, Put, Post, Delete, Options, Head, Patch, Trace and fixed fields under the OAS Path Item object | Supports only GET. +| Input parameters and HTTP bindings: Specifies the input parameters for the operation. | RAML parameters | OAS Parameter object | Generates data type providers for federation. +| Responses with multiple media types: Specifies the output parameter for the operation. | RAML responses | OAS Response object | Orchestrates queries (only JSON). +| Responses with bindings to HTTP status codes: Specifies the binding to the HTTP status code. | RAML responses | OAS Response object | Orchestrates queries (only 2xx responses). +| Callbacks: Specifies the asynchronous invocations and webhooks. | Not applicable | OAS Callback object | Not applicable +| Links: Specifies the static connections between endpoints in the specification, excluding hyperlinks in the data. | Not applicable | OAS Link object | Not applicable +4+| *Security model:* A declaration of which security mechanisms you can used across the APIs. +| OAuth 1.0: The API authentication requires using OAuth 1.0 as described in https://tools.ietf.org/html/rfc5849[RFC5849]. | RAML security schemes | Not applicable | Not applicable +| OAuth 2.0: The API authentication requires using OAuth 2.0 as described in https://tools.ietf.org/html/rfc6749[RFC6749]. | RAML security schemes | OAS Security Scheme object | Not applicable +| Basic: The API authentication relies on using Basic Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617]. | RAML security schemes | OAS Security Scheme object | Not applicable +| Digest: The API authentication relies on using Digest Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617] | RAML security schemes | Not applicable | Not applicable +| API Key: The API authentication relies on using API key (either as a header, a cookie parameter, or as a query parameter). | Not applicable | OAS Security Scheme object | Supported for federation. +| Open ID Connect: The API authentication relies on using OAuth2's common flows (implicit, password, client credentials and authorization code) defined in https://tools.ietf.org/html/draft-ietf-oauth-discovery-06[OpenID Connect Discovery]. | Not applicable | OAS Security Scheme object | Not applicable +| Pass through: Headers or query parameters are passed through to the API based on a defined mapping. | RAML security schemes | Not applicable | Not applicable +| Custom: The API authentication relies on another custom authentication method. | RAML security schemes | OAS Security Scheme object | Not applicable +4+| *Data description and validation:* Validation of any XML or JSON instance against inner elements follows the same restrictions as the validation against a regular XML or JSON schema. +| JSON schema constraints and support: The level of support or constraints on JSON schemas. This is the base for both. RAML Types is a superset | RAML JSON support | OAS Schema object | Generates type schemas in the federated API. +| Schema Inheritance: The combining and extending of model definitions by using properties of JSON Schema.| RAML type inheritance | *Simulated with `$allOf`, not proper inheritance, murky situation in OAS Schema* | Supports union types in the federated API. Scalars in inheritance are not supported. +| Type expressions: Type expressions can be used wherever a type is expected. Using type expressions, you can devise type unions, arrays, maps, and other things.| RAML type expressions | Not applicable | Supports union types in the federated API. Scalars in expression are not supported. +| XML Schema constraints and support: The level of support or constraints on XML schemas. | RAML XML support provided indirectly through RAML XML facets for RAML types. | Support provided indirectly through XML properties for the `Schema object` | Not applicable +| Examples: RAML or OAS examples of implementing validations. | RAML examples | OAS `Example object` | Not applicable +| Mandatory valid examples: Required examples that are valid. | Not applicable | Not applicable | Not applicable +4+| *Meta-model extensibility:* Defines the ability to extend the format to describe additional details or objects. +| Custom property extensions: Extensions and additional details for custom properties. | Annotations | OAS specification extensions | Not applicable +| Custom node extensions: Additional details for custom node extensions. | Complex annotations | Not applicable | Not applicable +| Extensions schema: Additional details about extension schemas | Annotations can have a schema and can be validated |Not applicable | Not applicable +| Extensions semantics: Semantics to be used for defining extensions. | Not applicable | Not applicable | Not applicable +|=== diff --git a/modules/ROOT/pages/api-spec-support-exchange.adoc b/modules/ROOT/pages/api-spec-support-exchange.adoc index 1c14d985..b032acf8 100644 --- a/modules/ROOT/pages/api-spec-support-exchange.adoc +++ b/modules/ROOT/pages/api-spec-support-exchange.adoc @@ -1,10 +1,10 @@ -= API Specifications Support in Exchange += API Specifications Support in Anypoint Exchange ifndef::env-site,env-github[] include::_attributes.adoc[] endif::[] :keywords: api, instance, manager -You can implement your API specification in a way that best suits your needs. The following table explains how each of the features of the API specification is best implemented and the level of support provided for the specification in Anypoint Exchange. +You can implement your API specification in a way that best suits your needs. The following table explains how each of the features of the API specification is best implemented and the level of support provided for the specification in Exchange. [%header%autowidth.spread,cols="a,a,a,a"] |=== From 8d77cb31fe1c7283367cafe3fee5f85c848effc3 Mon Sep 17 00:00:00 2001 From: Rodgers-Glenn Date: Thu, 8 Jul 2021 14:06:18 -0400 Subject: [PATCH 15/18] Create api-spec-support-apikit.adoc --- .../ROOT/pages/api-spec-support-apikit.adoc | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 modules/ROOT/pages/api-spec-support-apikit.adoc diff --git a/modules/ROOT/pages/api-spec-support-apikit.adoc b/modules/ROOT/pages/api-spec-support-apikit.adoc new file mode 100644 index 00000000..6e3c3144 --- /dev/null +++ b/modules/ROOT/pages/api-spec-support-apikit.adoc @@ -0,0 +1,58 @@ += API Specifications Support in APIkit +ifndef::env-site,env-github[] +include::_attributes.adoc[] +endif::[] +:keywords: api, instance, manager + +You can implement your API specification in a way that best suits your needs. The following table explains how each of the features of the API specification is best implemented and the level of support provided for the specification in APIkit. + +[%header%autowidth.spread,cols="a,a,a,a"] +|=== +| Feature: Description| RAML Implementation | OAS Implementation | APIkit Support +4+| *Modularity:* The ability to break an API specification into reusable and shared units. +| API Document: The main API specification description metadata, which is the entry point for the specification. | RAML root document | OAS root document | Can be scaffolded. +| Libraries: The unit containing collections of related reusable description elements. | RAML library | Can be implemented using an empty OAS specification containing multiple components. | Not applicable +| Fragments: Stand-alone component of the specification that describes a specific element. | RAML fragment | Can be implemented using an empty OAS specification containing a single component.| Not applicable +| Overlays: A partial description of the API specification that you can use to overwrite non-functional aspects of the API specification by composing it with the original specification, for example, translating the documentation to other languages. | RAML overlay | Can be simulated with JSON patch or merge preprocessing. | Modified APIs can be scaffolded. +| Extensions: A partial description of the API spec that can be used to overwrite non-functional aspects of the API spec composing it with the original specification, like for example adding the security information for a managed API | RAML extension | Can be simulated with JSON patch or merge preprocessing. | Modified APIs can be scaffolded. +4+| *Reusability:* The ability to reuse the API description in multiple specifications. +| Inline declarations and references: The ability to declare and reference elements from multiple documents. | Inclusion and named references to: datatypes, traits, resource types, and annotations declarations. | JSON reference and OAS components. | Inlines through AMF for scaffolding. +| Traits: Macros that extend operations in the functional model, such as pagination, that can be reused in multiple specifications for consistency | Operation macros and RAML traits | Not applicable | Inlines through AMF for scaffolding. +| Resource types: Macros that extend resources in the functional model with complex behavior and data definition that can be reused in multiple specifications for consistency | Endpoint macros and RAML resource types | Not applicable | Inlines through AMF for scaffolding. +4+| *API Metadata:* Provides metadata about the API that might be used by tooling as required. +| API Entrypoint: The main entry point for the API description, mostly human-readable information, such as title, version, license, and so forth. | RAML document top level information | OAS Open API object| Not applicable +| Server and protocols: Denotes the actual connectivity to the service | RAML base URI information | OAS Server object | Not applicable +| Terms of service & licensing: The user agreement and licensing information of the API | Only plain documentation | OAS Info object | Not applicable +| User documentation: Includes user guide and reference material that clarifies how the API works. | RAML description properties in different parts of the specification | OAS description properties in the specification objects | Not applicable +| Localized documentation: Specifies multi-lingual descriptions | Using overlays | Not applicable | Not applicable +| Tags: Classification of parts of the specification | Only use annotations | OAS Tag object | Not applicable +4+| *Functional model:* A declaration of the resources to use when RPCs are invoked. +| Endpoints: Refers to the resources and RPC invocations in the API | Because RAML is more RESTful, the RAML resources are more explicit in its working and allows for the nesting of those resources. | OAS Path Item objects under the Paths object | Scaffolds flows. +| Methods and bindings to HTTP uniform interface: Includes operations over the resource and information about how to invoke the RPC operation. | Get, Patch, Put, Post, Delete, Options, and head RAML operations | Get, Put, Post, Delete, Options, Head, Patch, Trace and fixed fields under the OAS Path Item object | Scaffolds flows. +| Input parameters and HTTP bindings: Specifies the input parameters for the operation. | RAML parameters | OAS Parameter object | Scaffolds flows. +| Responses with multiple media types: Specifies the output parameter for the operation. | RAML responses | OAS Response object | Scaffolds flows. +| Responses with bindings to HTTP status codes: Specifies the binding to the HTTP status code. | RAML responses | OAS Response object | Scaffolds flows. +| Callbacks: Specifies the asynchronous invocations and webhooks. | Not applicable | OAS Callback object | Not applicable +| Links: Specifies the static connections between endpoints in the specification, excluding hyperlinks in the data. | Not applicable | OAS Link object | Not applicable +4+| *Security model:* A declaration of which security mechanisms you can used across the APIs. +| OAuth 1.0: The API authentication requires using OAuth 1.0 as described in https://tools.ietf.org/html/rfc5849[RFC5849]. | RAML security schemes | Not applicable | Not applicable +| OAuth 2.0: The API authentication requires using OAuth 2.0 as described in https://tools.ietf.org/html/rfc6749[RFC6749]. | RAML security schemes | OAS Security Scheme object | Not applicable +| Basic: The API authentication relies on using Basic Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617]. | RAML security schemes | OAS Security Scheme object | Not applicable +| Digest: The API authentication relies on using Digest Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617] | RAML security schemes | Not applicable | Not applicable +| API Key: The API authentication relies on using API key (either as a header, a cookie parameter, or as a query parameter). | Not applicable | OAS Security Scheme object | Not applicable +| Open ID Connect: The API authentication relies on using OAuth2's common flows (implicit, password, client credentials and authorization code) defined in https://tools.ietf.org/html/draft-ietf-oauth-discovery-06[OpenID Connect Discovery]. | Not applicable | OAS Security Scheme object | Not applicable +| Pass through: Headers or query parameters are passed through to the API based on a defined mapping. | RAML security schemes | Not applicable | Not applicable +| Custom: The API authentication relies on another custom authentication method. | RAML security schemes | OAS Security Scheme object | Not applicable +4+| *Data description and validation:* Validation of any XML or JSON instance against inner elements follows the same restrictions as the validation against a regular XML or JSON schema. +| JSON schema constraints and support: The level of support or constraints on JSON schemas. This is the base for both. RAML Types is a superset | RAML JSON support | OAS Schema object | Automatic runtime validation. +| Schema Inheritance: The combining and extending of model definitions by using properties of JSON Schema.| RAML type inheritance | *Simulated with `$allOf`, not proper inheritance, murky situation in OAS Schema* | Flattened at runtime. +| Type expressions: Type expressions can be used wherever a type is expected. Using type expressions, you can devise type unions, arrays, maps, and other things.| RAML type expressions | Not applicable | Flattened at runtime. +| XML Schema constraints and support: The level of support or constraints on XML schemas. | RAML XML support provided indirectly through RAML XML facets for RAML types. | Support provided indirectly through XML properties for the `Schema object` | Automatic runtime validation. +| Examples: RAML or OAS examples of implementing validations. | RAML examples | OAS `Example object` | Not applicable +| Mandatory valid examples: Required examples that are valid. | Not applicable | Not applicable | Not applicable +4+| *Meta-model extensibility:* Defines the ability to extend the format to describe additional details or objects. +| Custom property extensions: Extensions and additional details for custom properties. | Annotations | OAS specification extensions | Used for advanced scaffolding (for example, OData annotations). +| Custom node extensions: Additional details for custom node extensions. | Complex annotations | Not applicable | Not applicable +| Extensions schema: Additional details about extension schemas | Annotations can have a schema and can be validated |Not applicable | Not applicable +| Extensions semantics: Semantics to be used for defining extensions. | Not applicable | Not applicable | Not applicable +|=== From fccd46425f90516cfdcf6456a9c58a36b510f6f9 Mon Sep 17 00:00:00 2001 From: Rodgers-Glenn Date: Thu, 8 Jul 2021 14:44:59 -0400 Subject: [PATCH 16/18] Created Rest Connect Doc and fixed a few spacing typos --- .../pages/api-spec-support-api-designer.adoc | 2 +- .../pages/api-spec-support-api-manager.adoc | 12 ++-- .../ROOT/pages/api-spec-support-exchange.adoc | 12 ++-- .../ROOT/pages/api-support-rest-connect.adoc | 58 +++++++++++++++++++ 4 files changed, 71 insertions(+), 13 deletions(-) create mode 100644 modules/ROOT/pages/api-support-rest-connect.adoc diff --git a/modules/ROOT/pages/api-spec-support-api-designer.adoc b/modules/ROOT/pages/api-spec-support-api-designer.adoc index b59e13f7..cd660f09 100644 --- a/modules/ROOT/pages/api-spec-support-api-designer.adoc +++ b/modules/ROOT/pages/api-spec-support-api-designer.adoc @@ -39,7 +39,7 @@ You can implement your API specification in a way that best suits your needs. Th | OAuth 2.0: The API authentication requires using OAuth 2.0 as described in https://tools.ietf.org/html/rfc6749[RFC6749]. | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. | Basic: The API authentication relies on using Basic Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617]. | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. | Digest: The API authentication relies on using Digest Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617] | RAML security schemes | Not applicable | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. -| API Key: The API authentication relies on using API key (either as a header, a cookie parameter, or as a query parameter). | Not applicable | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. +| API Key: The API authentication relies on using API key (either as a header, a cookie parameter, or as a query parameter). | Not applicable | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. | Open ID Connect: The API authentication relies on using OAuth2's common flows (implicit, password, client credentials and authorization code) defined in https://tools.ietf.org/html/draft-ietf-oauth-discovery-06[OpenID Connect Discovery]. | Not applicable | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. | Pass through: Headers or query parameters are passed through to the API based on a defined mapping. | RAML security schemes | Not applicable | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. | Custom: The API authentication relies on another custom authentication method. | RAML security schemes | OAS Security Scheme object | Allows editing and validations, and enables console rendering. Note that the security schemes might be out-of-sync with actual policy in API Manager. diff --git a/modules/ROOT/pages/api-spec-support-api-manager.adoc b/modules/ROOT/pages/api-spec-support-api-manager.adoc index e830a091..fa164856 100644 --- a/modules/ROOT/pages/api-spec-support-api-manager.adoc +++ b/modules/ROOT/pages/api-spec-support-api-manager.adoc @@ -35,12 +35,12 @@ You can implement your API specification in a way that best suits your needs. Th | Callbacks: Specifies the asynchronous invocations and webhooks. | Not applicable | OAS Callback object | Not applicable | Links: Specifies the static connections between endpoints in the specification, excluding hyperlinks in the data. | Not applicable | OAS Link object | Not applicable 4+| *Security model:* A declaration of which security mechanisms you can used across the APIs. -| OAuth 1.0: The API authentication requires using OAuth 1.0 as described in https://tools.ietf.org/html/rfc5849[RFC5849]. | RAML security schemes | Not applicable | Not applicable -| OAuth 2.0: The API authentication requires using OAuth 2.0 as described in https://tools.ietf.org/html/rfc6749[RFC6749]. | RAML security schemes | OAS Security Scheme object | Can apply as a policy. -| Basic: The API authentication relies on using Basic Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617]. | RAML security schemes | OAS Security Scheme object | Can apply as a policy. -| Digest: The API authentication relies on using Digest Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617] | RAML security schemes | Not applicable | Not applicable -| API Key: The API authentication relies on using API key (either as a header, a cookie parameter, or as a query parameter). | Not applicable | OAS Security Scheme object | Can apply as a policy. -| Open ID Connect: The API authentication relies on using OAuth2's common flows (implicit, password, client credentials and authorization code) defined in https://tools.ietf.org/html/draft-ietf-oauth-discovery-06[OpenID Connect Discovery]. | Not applicable | OAS Security Scheme object | Can apply as a policy. +| OAuth 1.0: The API authentication requires using OAuth 1.0 as described in https://tools.ietf.org/html/rfc5849[RFC5849]. | RAML security schemes | Not applicable | Not applicable +| OAuth 2.0: The API authentication requires using OAuth 2.0 as described in https://tools.ietf.org/html/rfc6749[RFC6749]. | RAML security schemes | OAS Security Scheme object | Can apply as a policy. +| Basic: The API authentication relies on using Basic Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617]. | RAML security schemes | OAS Security Scheme object | Can apply as a policy. +| Digest: The API authentication relies on using Digest Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617] | RAML security schemes | Not applicable | Not applicable +| API Key: The API authentication relies on using API key (either as a header, a cookie parameter, or as a query parameter). | Not applicable | OAS Security Scheme object | Can apply as a policy. +| Open ID Connect: The API authentication relies on using OAuth2's common flows (implicit, password, client credentials and authorization code) defined in https://tools.ietf.org/html/draft-ietf-oauth-discovery-06[OpenID Connect Discovery]. | Not applicable | OAS Security Scheme object | Can apply as a policy. | Pass through: Headers or query parameters are passed through to the API based on a defined mapping. | RAML security schemes | Not applicable | Does not need policy. | Custom: The API authentication relies on another custom authentication method. | RAML security schemes | OAS Security Scheme object | Can implement a custom policy. 4+| *Data description and validation:* Validation of any XML or JSON instance against inner elements follows the same restrictions as the validation against a regular XML or JSON schema. diff --git a/modules/ROOT/pages/api-spec-support-exchange.adoc b/modules/ROOT/pages/api-spec-support-exchange.adoc index b032acf8..4855156d 100644 --- a/modules/ROOT/pages/api-spec-support-exchange.adoc +++ b/modules/ROOT/pages/api-spec-support-exchange.adoc @@ -35,12 +35,12 @@ You can implement your API specification in a way that best suits your needs. Th | Callbacks: Specifies the asynchronous invocations and webhooks. | Not applicable | OAS Callback object | Enables console rendering. | Links: Specifies the static connections between endpoints in the specification, excluding hyperlinks in the data. | Not applicable | OAS Link object | Enables console rendering. 4+| *Security model:* A declaration of which security mechanisms you can used across the APIs. -| OAuth 1.0: The API authentication requires using OAuth 1.0 as described in https://tools.ietf.org/html/rfc5849[RFC5849]. | RAML security schemes | Not applicable | Allows advanced searches and enables console rendering. -| OAuth 2.0: The API authentication requires using OAuth 2.0 as described in https://tools.ietf.org/html/rfc6749[RFC6749]. | RAML security schemes | OAS Security Scheme object | Allows advanced searches and enables console rendering. -| Basic: The API authentication relies on using Basic Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617]. | RAML security schemes | OAS Security Scheme object | Allows advanced searches and enables console rendering. -| Digest: The API authentication relies on using Digest Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617] | RAML security schemes | Not applicable | Allows advanced searches and enables console rendering. -| API Key: The API authentication relies on using API key (either as a header, a cookie parameter, or as a query parameter). | Not applicable | OAS Security Scheme object | Allows advanced searches and enables console rendering. -| Open ID Connect: The API authentication relies on using OAuth2's common flows (implicit, password, client credentials and authorization code) defined in https://tools.ietf.org/html/draft-ietf-oauth-discovery-06[OpenID Connect Discovery]. | Not applicable | OAS Security Scheme object | Allows advanced searches and enables console rendering. +| OAuth 1.0: The API authentication requires using OAuth 1.0 as described in https://tools.ietf.org/html/rfc5849[RFC5849]. | RAML security schemes | Not applicable | Allows advanced searches and enables console rendering. +| OAuth 2.0: The API authentication requires using OAuth 2.0 as described in https://tools.ietf.org/html/rfc6749[RFC6749]. | RAML security schemes | OAS Security Scheme object | Allows advanced searches and enables console rendering. +| Basic: The API authentication relies on using Basic Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617]. | RAML security schemes | OAS Security Scheme object | Allows advanced searches and enables console rendering. +| Digest: The API authentication relies on using Digest Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617] | RAML security schemes | Not applicable | Allows advanced searches and enables console rendering. +| API Key: The API authentication relies on using API key (either as a header, a cookie parameter, or as a query parameter). | Not applicable | OAS Security Scheme object | Allows advanced searches and enables console rendering. +| Open ID Connect: The API authentication relies on using OAuth2's common flows (implicit, password, client credentials and authorization code) defined in https://tools.ietf.org/html/draft-ietf-oauth-discovery-06[OpenID Connect Discovery]. | Not applicable | OAS Security Scheme object | Allows advanced searches and enables console rendering. | Pass through: Headers or query parameters are passed through to the API based on a defined mapping. | RAML security schemes | Not applicable | Allows advanced searches and enables console rendering. | Custom: The API authentication relies on another custom authentication method. | RAML security schemes | OAS Security Scheme object | Allows advanced searches and enables console rendering. 4+| *Data description and validation:* Validation of any XML or JSON instance against inner elements follows the same restrictions as the validation against a regular XML or JSON schema. diff --git a/modules/ROOT/pages/api-support-rest-connect.adoc b/modules/ROOT/pages/api-support-rest-connect.adoc new file mode 100644 index 00000000..518ace8d --- /dev/null +++ b/modules/ROOT/pages/api-support-rest-connect.adoc @@ -0,0 +1,58 @@ += API Specifications Support in REST Connect +ifndef::env-site,env-github[] +include::_attributes.adoc[] +endif::[] +:keywords: api, instance, manager + +You can implement your API specification in a way that best suits your needs. The following table explains how each of the features of the API specification is best implemented and the level of support provided for the specification in REST Connect. + +[%header%autowidth.spread,cols="a,a,a,a"] +|=== +| Feature: Description| RAML Implementation | OAS Implementation | REST Connect Support +4+| *Modularity:* The ability to break an API specification into reusable and shared units. +| API Document: The main API specification description metadata, which is the entry point for the specification. | RAML root document | OAS root document | Generates a simple connector. +| Libraries: The unit containing collections of related reusable description elements. | RAML library | Can be implemented using an empty OAS specification containing multiple components. | Not applicable +| Fragments: Stand-alone component of the specification that describes a specific element. | RAML fragment | Can be implemented using an empty OAS specification containing a single component.| Not applicable +| Overlays: A partial description of the API specification that you can use to overwrite non-functional aspects of the API specification by composing it with the original specification, for example, translating the documentation to other languages. | RAML overlay | Can be simulated with JSON patch or merge preprocessing. | Connectors can be generated for modified APIs. +| Extensions: A partial description of the API spec that can be used to overwrite non-functional aspects of the API spec composing it with the original specification, like for example adding the security information for a managed API | RAML extension | Can be simulated with JSON patch or merge preprocessing. | Connectors can be generated for modified APIs. +4+| *Reusability:* The ability to reuse the API description in multiple specifications. +| Inline declarations and references: The ability to declare and reference elements from multiple documents. | Inclusion and named references to: datatypes, traits, resource types, and annotations declarations. | JSON reference and OAS components. | Inlines through AMF for connectivity. +| Traits: Macros that extend operations in the functional model, such as pagination, that can be reused in multiple specifications for consistency | Operation macros and RAML traits | Not applicable | Inlines through AMF for connectivity. +| Resource types: Macros that extend resources in the functional model with complex behavior and data definition that can be reused in multiple specifications for consistency | Endpoint macros and RAML resource types | Not applicable | Inlines through AMF for connectivity. +4+| *API Metadata:* Provides metadata about the API that might be used by tooling as required. +| API Entrypoint: The main entry point for the API description, mostly human-readable information, such as title, version, license, and so forth. | RAML document top level information | OAS Open API object| Not applicable +| Server and protocols: Denotes the actual connectivity to the service | RAML base URI information | OAS Server object | Provides the value for the connection. +| Terms of service & licensing: The user agreement and licensing information of the API | Only plain documentation | OAS Info object | Not applicable +| User documentation: Includes user guide and reference material that clarifies how the API works. | RAML description properties in different parts of the specification | OAS description properties in the specification objects | Not applicable +| Localized documentation: Specifies multi-lingual descriptions | Using overlays | Not applicable | Not applicable +| Tags: Classification of parts of the specification | Only use annotations | OAS Tag object | Not applicable +4+| *Functional model:* A declaration of the resources to use when RPCs are invoked. +| Endpoints: Refers to the resources and RPC invocations in the API | Because RAML is more RESTful, the RAML resources are more explicit in its working and allows for the nesting of those resources. | OAS Path Item objects under the Paths object | Provides options for connectivity. +| Methods and bindings to HTTP uniform interface: Includes operations over the resource and information about how to invoke the RPC operation. | Get, Patch, Put, Post, Delete, Options, and head RAML operations | Get, Put, Post, Delete, Options, Head, Patch, Trace and fixed fields under the OAS Path Item object | Provides options for connectivity. +| Input parameters and HTTP bindings: Specifies the input parameters for the operation. | RAML parameters | OAS Parameter object | Provides options for connectivity. +| Responses with multiple media types: Specifies the output parameter for the operation. | RAML responses | OAS Response object | Provides options for connectivity. +| Responses with bindings to HTTP status codes: Specifies the binding to the HTTP status code. | RAML responses | OAS Response object | Provides options for connectivity. +| Callbacks: Specifies the asynchronous invocations and webhooks. | Not applicable | OAS Callback object | Not applicable +| Links: Specifies the static connections between endpoints in the specification, excluding hyperlinks in the data. | Not applicable | OAS Link object | Not applicable +4+| *Security model:* A declaration of which security mechanisms you can used across the APIs. +| OAuth 1.0: The API authentication requires using OAuth 1.0 as described in https://tools.ietf.org/html/rfc5849[RFC5849]. | RAML security schemes | Not applicable | Not applicable +| OAuth 2.0: The API authentication requires using OAuth 2.0 as described in https://tools.ietf.org/html/rfc6749[RFC6749]. | RAML security schemes | OAS Security Scheme object | Supported in connectors. +| Basic: The API authentication relies on using Basic Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617]. | RAML security schemes | OAS Security Scheme object | Supported in connectors. +| Digest: The API authentication relies on using Digest Access Authentication as described in https://tools.ietf.org/html/rfc2617[RFC2617] | RAML security schemes | Not applicable | Supported in connectors. +| API Key: The API authentication relies on using API key (either as a header, a cookie parameter, or as a query parameter). | Not applicable | OAS Security Scheme object | Not applicable +| Open ID Connect: The API authentication relies on using OAuth2's common flows (implicit, password, client credentials and authorization code) defined in https://tools.ietf.org/html/draft-ietf-oauth-discovery-06[OpenID Connect Discovery]. | Not applicable | OAS Security Scheme object | Not applicable +| Pass through: Headers or query parameters are passed through to the API based on a defined mapping. | RAML security schemes | Not applicable | Supported in connectors. +| Custom: The API authentication relies on another custom authentication method. | RAML security schemes | OAS Security Scheme object | Not applicable +4+| *Data description and validation:* Validation of any XML or JSON instance against inner elements follows the same restrictions as the validation against a regular XML or JSON schema. +| JSON schema constraints and support: The level of support or constraints on JSON schemas. This is the base for both. RAML Types is a superset | RAML JSON support | OAS Schema object | Not applicable +| Schema Inheritance: The combining and extending of model definitions by using properties of JSON Schema.| RAML type inheritance | *Simulated with `$allOf`, not proper inheritance, murky situation in OAS Schema* | Not applicable +| Type expressions: Type expressions can be used wherever a type is expected. Using type expressions, you can devise type unions, arrays, maps, and other things.| RAML type expressions | Not applicable | Not applicable +| XML Schema constraints and support: The level of support or constraints on XML schemas. | RAML XML support provided indirectly through RAML XML facets for RAML types. | Support provided indirectly through XML properties for the `Schema object` | Not applicable +| Examples: RAML or OAS examples of implementing validations. | RAML examples | OAS `Example object` | Not applicable +| Mandatory valid examples: Required examples that are valid. | Not applicable | Not applicable | Not applicable +4+| *Meta-model extensibility:* Defines the ability to extend the format to describe additional details or objects. +| Custom property extensions: Extensions and additional details for custom properties. | Annotations | OAS specification extensions | Used to customize connectivity details. +| Custom node extensions: Additional details for custom node extensions. | Complex annotations | Not applicable | Not applicable +| Extensions schema: Additional details about extension schemas | Annotations can have a schema and can be validated |Not applicable | Not applicable +| Extensions semantics: Semantics to be used for defining extensions. | Not applicable | Not applicable | Not applicable +|=== From bd4d31293df16c214b30bb6e82f7a4e7fadceae9 Mon Sep 17 00:00:00 2001 From: Rodgers-Glenn Date: Thu, 8 Jul 2021 16:21:20 -0400 Subject: [PATCH 17/18] Changed a few wordings. --- modules/ROOT/pages/api-spec-support-api-manager.adoc | 8 ++++---- modules/ROOT/pages/api-support-rest-connect.adoc | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/api-spec-support-api-manager.adoc b/modules/ROOT/pages/api-spec-support-api-manager.adoc index fa164856..fbd34b72 100644 --- a/modules/ROOT/pages/api-spec-support-api-manager.adoc +++ b/modules/ROOT/pages/api-spec-support-api-manager.adoc @@ -10,11 +10,11 @@ You can implement your API specification in a way that best suits your needs. Th |=== | Feature: Description| RAML Implementation | OAS Implementation | API Manager Support 4+| *Modularity:* The ability to break an API specification into reusable and shared units. -| API Document: The main API specification description metadata, which is the entry point for the specification. | RAML root document | OAS root document | Manages the API instance associated with the API (RAML only). +| API Document: The main API specification description metadata, which is the entry point for the specification. | RAML root document | OAS root document | API instance associated with the API (RAML only) can be managed. | Libraries: The unit containing collections of related reusable description elements. | RAML library | Can be implemented using an empty OAS specification containing multiple components. | Not applicable | Fragments: Stand-alone component of the specification that describes a specific element. | RAML fragment | Can be implemented using an empty OAS specification containing a single component.| Not applicable -| Overlays: A partial description of the API specification that you can use to overwrite non-functional aspects of the API specification by composing it with the original specification, for example, translating the documentation to other languages. | RAML overlay | Can be simulated with JSON patch or merge preprocessing. | Manages modified APIs. -| Extensions: A partial description of the API spec that can be used to overwrite non-functional aspects of the API spec composing it with the original specification, like for example adding the security information for a managed API | RAML extension | Can be simulated with JSON patch or merge preprocessing. | Manages modified APIs. +| Overlays: A partial description of the API specification that you can use to overwrite non-functional aspects of the API specification by composing it with the original specification, for example, translating the documentation to other languages. | RAML overlay | Can be simulated with JSON patch or merge preprocessing. | Modified APIs can be managed. +| Extensions: A partial description of the API spec that can be used to overwrite non-functional aspects of the API spec composing it with the original specification, like for example adding the security information for a managed API | RAML extension | Can be simulated with JSON patch or merge preprocessing. | Modified APIs can be managed. 4+| *Reusability:* The ability to reuse the API description in multiple specifications. | Inline declarations and references: The ability to declare and reference elements from multiple documents. | Inclusion and named references to: datatypes, traits, resource types, and annotations declarations. | JSON reference and OAS components. | Inlines through AMF for management. | Traits: Macros that extend operations in the functional model, such as pagination, that can be reused in multiple specifications for consistency | Operation macros and RAML traits | Not applicable | Inlines through AMF for management. @@ -42,7 +42,7 @@ You can implement your API specification in a way that best suits your needs. Th | API Key: The API authentication relies on using API key (either as a header, a cookie parameter, or as a query parameter). | Not applicable | OAS Security Scheme object | Can apply as a policy. | Open ID Connect: The API authentication relies on using OAuth2's common flows (implicit, password, client credentials and authorization code) defined in https://tools.ietf.org/html/draft-ietf-oauth-discovery-06[OpenID Connect Discovery]. | Not applicable | OAS Security Scheme object | Can apply as a policy. | Pass through: Headers or query parameters are passed through to the API based on a defined mapping. | RAML security schemes | Not applicable | Does not need policy. -| Custom: The API authentication relies on another custom authentication method. | RAML security schemes | OAS Security Scheme object | Can implement a custom policy. +| Custom: The API authentication relies on another custom authentication method. | RAML security schemes | OAS Security Scheme object | Can implement custom policies. 4+| *Data description and validation:* Validation of any XML or JSON instance against inner elements follows the same restrictions as the validation against a regular XML or JSON schema. | JSON schema constraints and support: The level of support or constraints on JSON schemas. This is the base for both. RAML Types is a superset | RAML JSON support | OAS Schema object | Not applicable | Schema Inheritance: The combining and extending of model definitions by using properties of JSON Schema.| RAML type inheritance | *Simulated with `$allOf`, not proper inheritance, murky situation in OAS Schema* | Not applicable diff --git a/modules/ROOT/pages/api-support-rest-connect.adoc b/modules/ROOT/pages/api-support-rest-connect.adoc index 518ace8d..362265a5 100644 --- a/modules/ROOT/pages/api-support-rest-connect.adoc +++ b/modules/ROOT/pages/api-support-rest-connect.adoc @@ -10,7 +10,7 @@ You can implement your API specification in a way that best suits your needs. Th |=== | Feature: Description| RAML Implementation | OAS Implementation | REST Connect Support 4+| *Modularity:* The ability to break an API specification into reusable and shared units. -| API Document: The main API specification description metadata, which is the entry point for the specification. | RAML root document | OAS root document | Generates a simple connector. +| API Document: The main API specification description metadata, which is the entry point for the specification. | RAML root document | OAS root document | Can Generate a simple connector. | Libraries: The unit containing collections of related reusable description elements. | RAML library | Can be implemented using an empty OAS specification containing multiple components. | Not applicable | Fragments: Stand-alone component of the specification that describes a specific element. | RAML fragment | Can be implemented using an empty OAS specification containing a single component.| Not applicable | Overlays: A partial description of the API specification that you can use to overwrite non-functional aspects of the API specification by composing it with the original specification, for example, translating the documentation to other languages. | RAML overlay | Can be simulated with JSON patch or merge preprocessing. | Connectors can be generated for modified APIs. From cff98f4375f666f5bc622e4c2c290799f2f97fff Mon Sep 17 00:00:00 2001 From: Rodgers-Glenn Date: Thu, 8 Jul 2021 16:28:41 -0400 Subject: [PATCH 18/18] Added spec docs to nav, correct use of APIkit, updated name for spec REST Connect. --- modules/ROOT/nav.adoc | 5 +++++ modules/ROOT/pages/api-compatibility-matrix.adoc | 6 ++---- ...rest-connect.adoc => api-spec-support-rest-connect.adoc} | 0 3 files changed, 7 insertions(+), 4 deletions(-) rename modules/ROOT/pages/{api-support-rest-connect.adoc => api-spec-support-rest-connect.adoc} (100%) diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 39928ce5..34f4b30f 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -10,6 +10,11 @@ * xref:intro-platform-hosting.adoc[Hosting Options] * xref:api-compatibility-matrix.adoc[Anypoint Platform Compatibility Support for Restful-APIs by Products] ** xref:api-spec-support-api-designer.adoc[API Designer] + ** xref:api-spec-support-exchange.adoc[Anypoint Exchange] + ** xref:api-spec-support-api-manager.adoc[API Manager] + ** xref:api-spec-support-datagraph.adoc[Anypoint Datagraph] + ** xref:api-spec-support-api-kit.adoc[APIkit] + ** xref:api-spec-support-rest-connect.adoc[REST Connect] * xref:browser-support.adoc[Browser Support] * xref:glossary.adoc[Glossary] * xref:contribute.adoc[Contribute to MuleSoft Documentation] diff --git a/modules/ROOT/pages/api-compatibility-matrix.adoc b/modules/ROOT/pages/api-compatibility-matrix.adoc index 1c5ba4fd..aae325a7 100644 --- a/modules/ROOT/pages/api-compatibility-matrix.adoc +++ b/modules/ROOT/pages/api-compatibility-matrix.adoc @@ -3,7 +3,7 @@ ifndef::env-site,env-github[] include::_attributes.adoc[] endif::[] -You can design an API in Anypoint Platform using the RESTful API Modeling Language (RAML) or the OpenAPI Specification (OAS) format based on your needs. Both RAML and OAS specifications have a common REST API model and provide similar features. +You can design an API in Anypoint Platform using the RESTful API Modeling Language (RAML) or the OpenAPI Specification (OAS) format based on your needs. Both RAML and OAS specifications have a common REST API model and provide similar features. MuleSoft's underlying metadata libraries and components, which includes AMF (parser) and ALS (language server for IDEs), provides interoperability using a common metadata model and enables data definition reuse, use of linting rules, and provides translation to and from both RAML and OAS specifications. @@ -13,7 +13,5 @@ Before you start designing an API, learn more about how each of the specificatio * xref:api-spec-support-exchange.adoc[Anypoint Exchange] * xref:api-spec-support-api-manager.adoc[API Manager] * xref:api-spec-support-datagraph.adoc[Anypoint Datagraph] -* xref:api-spec-support-api-kit.adoc[API Kit] +* xref:api-spec-support-api-kit.adoc[APIkit] * xref:api-spec-support-rest-connect.adoc[REST Connect] - - diff --git a/modules/ROOT/pages/api-support-rest-connect.adoc b/modules/ROOT/pages/api-spec-support-rest-connect.adoc similarity index 100% rename from modules/ROOT/pages/api-support-rest-connect.adoc rename to modules/ROOT/pages/api-spec-support-rest-connect.adoc