Explaining and Creating API Specifications with Anypoint Platform
Specification-first design
Anypoint Platform lets you define a contract before any implementation exists. RAML 1.0 is authored in Design Center's API Designer, either as a stand-alone API specification project or as a fragment project (library, data type, trait, resource type, or OAS component) published to Exchange and reused with uses: (RAML) or $ref (OAS). Exams lean hard on the difference between traits - reusable sets of method-level properties such as headers, query parameters, and responses - and resource types - reusable templates that carry whole methods, optionally parameterized with <<parameters>>. A resource type answers "which operations does this collection support?"; a trait answers "what does every method of this kind declare?".
Mocking, publishing, implementing
Enabling the mocking service gives a live endpoint that returns the examples blocks. A spec with schemas but no examples mocks poorly - a common distractor. Publishing to Exchange creates a versioned asset others can depend on; you must bump the version to republish. From a RAML or OAS spec you can scaffold an implementation with the APIkit Router, which generates a main flow, method flows, and a console flow.
Traps
- RAML traits, resource types, and libraries have no OAS 3.0 equivalent; fragments are format-specific.
- A RAML file's first line must be
#%RAML 1.0, andtitleplus a base URI are needed to get a usable mock endpoint. - Editing the spec does not change an already-deployed app; you must re-scaffold and redeploy.
- Spec-first vs code-first: APIkit only generates flows for operations the spec declares.
Rule of thumb
If the repetition lives inside a method (headers, query params, responses), use a trait. If it spans multiple methods on the same resource, use a parameterized resource type.