---
schema_version: "1"
id: f404803bca73737781d14ea4a8177f943ea8d7307fe39058c73266bf3fe6f9ea
title: Best Practices when using API Designer
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/design-center/design-best-practices.md
canonical_url: https://docs.mulesoft.com/design-center/design-best-practices
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 12a71391d730c2809eff21d1eda017968f37ed5b25148d61c37c4f62bdae738d
description: MuleSoft Documentation Site
latest: true
---
---
product: Design Center
---

# Best Practices when using API Designer

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

When you perform tasks on Design Center, you might encounter issues. Use the following topics to
help you resolve them.

## API Designer Best Practices

- 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.

### API Designer Resources

When using API Designer, the required resources to parse the specification depend on the users own
resources. For API Designer to function properly, ensure your computer has the following minimum
resources available when using API Designer:

- 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.

### 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 \]