Contact Us 1-800-596-4880
  1. Homepage
  2. Design Center
  3. Designing API Specs and Fragments

  4. Create and Publish an API Specification or Fragment from an External File

Create and Publish an API Specification or Fragment from an External File

Use API Designer to create a new API specification or an API fragment from an existing external file. API Designer supports importing from JSON, RAML, or YML files. You can also import API specifications and fragments from an existing project.

Procedure

  1. On the Projects page of Design Center, click the Create new button and then click Import from File.

  2. Specify a name to give to the imported project.

  3. Click Choose file, then browse your filesystem for the you want to import.

    You can create a new project from one following file types:

    • JSON

    • RAML

    • YAML

    • a ZIP file that contains an existing project.

  4. Click Import as…​ then choose either API Specification or API Fragment.

API Designer opens the API specification or fragment in a new project using the text editor. API Designer uses the existing name for each file of the project. You can change these names as necessary.

Modifying Your API Specification or Fragment

While you are working in the editor, you can navigate through and manipulate the content of your specification. Press F1 at any time to see a list of them. This list also displays keyboard shortcuts for most of the commands.

You can also perform these tasks:

Import files and API fragments into your project

You can import files, either separately or bundled in ZIP files. The files can be RAML 1.0 files, JSON files, or OpenAPI Specification (OAS) 2.0 or 3.0 files (either JSON or YAML). The files can be on your computer or you can specify a URL for them if they are located online.

For more information about importing files and steps for how to import them, see "Import Files into an API Project", which is linked to from the See also section at the end of this topic.

For information about adding API fragments to your project, see "Add a RAML API Fragment to an API-Specification Project as a Dependency", which is linked to from the See also section at the end of this topic.

Simulate calls to your API

Even while you are drafting an API specification, you can simulate calls to endpoints for which you have specified:

  • An HTTP status code the API returns, if successful

  • An example of data the actual implementation would return

    For more information, see Simulate Calls to an API.

Export your API project or specification

At any time, you can export your project as a ZIP file. Click the gear icon in the top-right corner of the text editor and select Download Project.

Download files

Click the dots to the right of the file name and select Download.

Download files in a different format

Click the dots to the right of the file name of a specification and select Download as. You can download your specification in one of the other supported formats. If your specification is in RAML, you can download it in OAS YAML or in OAS JSON. If your specification is in OAS, you can download it in RAML 0.8 or in RAML 1.0.

The files downloaded through this option are not guaranteed to be valid. This option is intended to provide the basis for the development of a new specification or the continuation of the development of the original specification in a new format.

What to Do Next

If you are satisfied with your API specification, you can publish it to Exchange. See Publish an API Specification.