Skip to content

des-designing-api-specs.adoc

Latest commit

 

History

History
110 lines (76 loc) · 3.88 KB

des-designing-api-specs.adoc

File metadata and controls

110 lines (76 loc) · 3.88 KB

Designing API Specs and Fragments

reuse::partial$beta-banner.adoc

Use Anypoint Code Builder to create, design, test, and publish new API specifications to Exchange.

The process for designing API specifications is:

For source management options, see SCM for API Design Projects.

Supported Languages for API Specs

Supported OAS and RAML versions are:

  • OAS 2.0 (JSON)

  • OAS 2.0 (YAML)

  • OAS 3.0 (JSON)

  • OAS 3.0 (YAML)

  • RAML 1.0

  • RAML 0.8

Supported AsyncAPI versions are:

  • AsyncAPI 2.6 (JSON)

  • AsyncAPI 2.6 (YAML)

For gRPC API specifications, Anypoint Code Builder supports Protocol Buffers (Protobuf 3). See des-design-grpc-api-spec.adoc.

Supported Specification Languages for API Fragments

Create, include, or reference API fragments within your API specification.

Supported API specification languages and syntaxes for API fragments are:

  • OAS 3.0

    • YAML

    • JSON

  • RAML 1.0

    See the RAML 1.0 specification for descriptions of these types:

    • Trait

    • Resource

    • Library

    • Data Type

    • User Documentation

    • Example

  • JSON Schema

  • Avro 1.9.0 schema

  • gRPC fragments (Protobuf 3)

    Reusable Protobuf definitions (for example, message or enum types) published as API fragment assets. See Publish a gRPC Fragment to Exchange.

Minimum Resource Requirements for the Desktop IDE

When parsing an API specification, the desktop IDE depends on your computer’s resources. To avoid issues, ensure that your computer has the following minimum resources available:

anypoint-code-builder::partial$acb-api-design.adoc

Best Practices

To avoid common issues, follow these guidelines:

anypoint-code-builder::partial$acb-api-design.adoc

+ This best practice applies to the cloud IDE only.

OAS Specification Best Practices

anypoint-code-builder::partial$acb-api-design.adoc

RAML Specification Best Practices

anypoint-code-builder::partial$acb-api-design.adoc

Source Control for API Design Projects

anypoint-code-builder::partial$acb-reusable-steps.adoc Source control options for API design projects depend on how and when you created the project:

  • As of the February 2024 release, design projects that you create from scratch in Anypoint Code Builder with Design an API (see Create a New API Specification Project) or with the command MuleSoft: Design an API no longer use MuleSoft VCS to store and sync changes.

  • If you prefer to use your own remote repository, GitHub is one option. To store your API project in a repository on GitHub, without synchronizing with the project in MuleSoft VCS, see publish your project files to another repository.

anypoint-code-builder::partial$acb-reusable-steps.adoc