---
schema_version: "1"
id: f2eedebc6eb891a451d1bebe22b89e7f71c43f7ee6fa9fc9699de9e907e1be0d
title: Designing API Specs and Fragments
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/anypoint-code-builder/des-designing-api-specs.md
canonical_url: https://docs.mulesoft.com/anypoint-code-builder/des-designing-api-specs
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 3ca444ee248b68e360adfd6c2f01e78caa266519f91d47e5070868a375d842b3
description: MuleSoft Documentation Site
latest: true
---
---
product: Anypoint Code Builder
version: master
---

# Designing API Specs and Fragments

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

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

The process for designing API specifications is:

1.  [Create or import and test your API specification](https://docs.mulesoft.com/anypoint-code-builder/des-create-api-specs)

2.  [Optionally, create and add fragments to your specification](https://docs.mulesoft.com/anypoint-code-builder/des-create-api-fragments).

3.  [Publish your API specifications to Exchange](https://docs.mulesoft.com/anypoint-code-builder/des-publish-api-spec-to-exchange).

For source management options, see [SCM for API Design Projects](https://docs.mulesoft.com/anypoint-code-builder/start-scm#anypoint-scm).

## 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)

- OAS 3.1 (JSON)

- OAS 3.1 (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
[Designing a gRPC API Specification with Anypoint Code Builder](https://docs.mulesoft.com/anypoint-code-builder/des-design-grpc-api-spec).

## 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 and 3.1

  - 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](https://docs.mulesoft.com/anypoint-code-builder/des-design-grpc-api-spec#publish-a-grpc-fragment-to-exchange).

## Minimum Resource Requirements for Anypoint Code Builder

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

- 8 GB RAM

- Ryzen series 5 / Intel i5 CPU or higher

To achieve optimal parser performance, keep the total project size for all files in your design
project below 500 KB.

A project size that exceeds 1.5 MB severely affects validation time.

## Best Practices

To avoid common issues, follow these guidelines:

- Divide your fragments into short, reusable dependencies when possible.

- Keep only one version of the same dependency.

- Keep only one browser tab open at a time.

- Before designing an OAS or RAML API specification, review
  [OAS Specification Best Practices](#apid-best-practices-oas) or
  [RAML Specification Best Practices](#apid-best-practices-raml)

### OAS Specification Best Practices

- Use the `$ref` property to define reusable components. To improve parsing efficiency, reference
  each component from the API specification instead of duplicating component definitions, for
  example:

  components: schemas: User: type: object properties: id: type: integer

  paths: /users: get: responses: '200': description: Successful response content: application/json:
  schema: $ref: '#/components/schemas/User'

- Use simpler types to represent your data if possible. Avoid unnecessary nesting and complicated
  types, for example:

  properties: age: type: integer # Prefer simple types over complex types like objects

- Use the `enum` property for fields with a fixed set of values to improve parsing efficiency:

  properties: status: type: string enum: \[active, inactive\]

- Use simple nesting for objects to simplify the structure and improve readability and parsing
  efficiency:

  \# Good properties: name: type: string address: type: string

  # Avoid

  properties: user: type: object properties: profile: type: object properties: name: type: string

- Use `response` headers instead of the response body to provide additional information, for
  example:

  responses: '200': description: Successful response headers: X-Rate-Limit-Limit: description: The
  number of requests allowed in the current period schema: type: integer

- Provide concise and short examples:

  Book: type: string example: "Explain the string with as few words as possible."

- When using union-type properties, use `oneOf` to represent union-type object fields, `allOf` to
  represent an intersection type and composite objects and fields, and `anyOf` when defining a
  property with multiple possible data structures.

### RAML Specification Best Practices

- When extracting RAML fragments, import each fragment as a local declaration first:

  Create a fragment file, and before publishing the fragment to Anypoint Exchange, import the local
  fragment file to validate that the fragment works as expected. If the fragment works, publish the
  fragment to Exchange so you can reuse the fragment in your API specifications instead of
  duplicating it.

- Reuse data types as declarations.

- Use inheritance only when needed:

  Car: description: This is a car properties: brand: string model: string example: brand: Toyota
  model: Corolla Person: properties: owns: Car

- Use short unions:

  Person: type: Employee | Customer

- Use simple traits, and avoid combining traits with resource type properties:

  /basic: type: {resourceTypes.fhirResourceType: { postExample : !include
  /examples/requests/post\_resource.json, getExample : !include
  /examples/responses/get\_resource.json, bundleName : basic.BasicBundle } } /\_search: get: is: \[
  searchParams \] post: is: \[ POSTSearchParams \]

## Source Control for API Design Projects

Use source control management (SCM) to store and share your design, integration, and implementation
projects. 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](https://docs.mulesoft.com/anypoint-code-builder/des-create-api-specs#design-new-api-spec)) or with the
  command `MuleSoft: Design an API` no longer use MuleSoft VCS to store and sync changes.

- API design projects
  [imported to Anypoint Code Builder from Design Center](https://docs.mulesoft.com/anypoint-code-builder/des-create-api-specs#import-spec) or
  created in Anypoint Code Builder before the February 2024 release automatically connect to
  MuleSoft VCS, which enables you to sync with a corresponding design project.

  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](https://docs.mulesoft.com/anypoint-code-builder/start-scm#add-extra-repo).

For source control options, see [Controlling Source Files](https://docs.mulesoft.com/anypoint-code-builder/start-scm).