Skip to content

imp-implement-api-specs.adoc

Latest commit

 

History

History
338 lines (291 loc) · 13.4 KB

imp-implement-api-specs.adoc

File metadata and controls

338 lines (291 loc) · 13.4 KB

Implementing OAS, RAML, AsyncAPI, and GraphQL APIs

reuse::partial$beta-banner.adoc

After you create your API spec, use Anypoint Code Builder to scaffold your API into a Mule project for your implementation or integration.

Anypoint Code Builder uses the configuration defined in the spec to autogenerate a basic interface in your implementation project. This interface includes flows for each endpoint or operation, a built-in XML-based router, and error handlers, which you then implement within a Mule application.

The process you use to implement your API depends on whether you already created a project for your integration or implementation, or published the spec to Exchange:

Scaffold an API into a New Project

If you have not already created a project, use Anypoint Code Builder to scaffold the API in a new Mule project:

+ image::anypoint-code-builder-view.png["Anypoint Code Builder icon highlighted in the activity bar"] partial$acb-reusable-steps.adoc

+ image::imp-api-search.png["Search an API from Exchange"]

+ The form shows the selected API spec, for example:

+ OAS Example API selected in the Implement an API Specification form . Click Create Project.

+ When you create the project, Anypoint Code Builder:

+ ** Adds the API spec as a dependency in your project’s pom.xml file:

+ partial$acb-reusable-steps.adoc Adds the Mule and Java versions to the project’s mule-artifact.json file. Scaffolds your API into the new Mule project and opens the configuration XML file.

+ The configuration XML file includes the interface for your implementation project, with flows for each endpoint in the spec, error handlers, and a built-in router, for example:

+ OAS Example Integration in Anypoint Code Builder This example includes:

+

  • The main flow

  • An HTTP Listener with a built-in router

  • Several error handlers

+ For GraphQL APIs, Anypoint Code Builder also creates a data fetcher (<graphql-router:data-fetcher>) as a source for each Mule flow. See the tut-graphql-implement-api.adoc tutorial for an example GraphQL API and apikit::apikit-graphql-api-mapping.adoc for more information about data fetchers.

You can now implement the interface within the Mule app.

Import an API Spec into a Project

If you have created an integration project, you can scaffold an interface into the project by importing an API spec from Exchange. In this case, Anypoint Code Builder creates a separate configuration XML file for the interface in your integration project.

  1. In Anypoint Code Builder, open your integration project in the Explorer view, for example, my-project-name. partial$acb-reusable-steps.adoc partial$acb-reusable-steps.adoc

    Assets from Exchange dropdown

  2. Select the API spec to import.

  3. At the prompt, select the version of the API spec, such as v1.0.1.

  4. When prompted to scaffold the API dependency, select Yes.

    When you scaffold the API dependency, Anypoint Code Builder:

    • Adds the API spec as a dependency in your project’s pom.xml file:

    • Adds the Mule and Java versions to the mule-artifact.json file:

    • Adds a new configuration XML file, such as oas-example.xml, to the project:

      New configuration file in the Explorer view

      The new configuration XML file includes the interface for your integration project, with flows for each endpoint in the spec, error handlers, and a built-in router, for example:

      OAS Example Integration in Anypoint Code Builder

      This example includes:

      • The main flow

      • An HTTP Listener with a built-in router

      • Several error handlers

        For GraphQL APIs, Anypoint Code Builder also creates a data fetcher (<graphql-router:data-fetcher>) as a source for each Mule flow. See the tut-graphql-implement-api.adoc tutorial for an example GraphQL API and apikit::apikit-graphql-api-mapping.adoc for more information about data fetchers.

You can now implement the interface within the Mule app.

Re-scaffold an API Specification into a Project

Re-scaffolding enables you to update a project in the IDE with the latest changes and version of an API spec in Anypoint Exchange. Re-scaffolding updates the configuration XML and pom.xml in your project. To re-scaffold a spec defined in a local API design project that is not published to Exchange, see imp-implement-local-apis.adoc, instead.

This procedure assumes that an updated version of the spec is available from Exchange, for example, a 2.0.0 version:

Selecting a new version of an API spec from Exchange

  1. In Anypoint Code Builder, open your implementation project in the Explorer view, for example, my-implementation-project. partial$acb-reusable-steps.adoc partial$acb-reusable-steps.adoc

    Assets from Exchange dropdown

  2. At the prompt, select the version of the API spec, such as v2.0.0.

  3. When prompted to scaffold the API dependency, select Yes.

    When you scaffold the API dependency, Anypoint Code Builder:

    • Adds the API spec as a dependency in your project’s pom.xml file:

      <dependency>
    <groupId>e91cab06-650b-4634-9c6f-5bc4f4fc4d17</groupId>
    <artifactId>phoneSync1005</artifactId>
    <version>2.0.0</version>
    <classifier>oas</classifier>
    <type>zip</type>
</dependency>

    • Updates the configuration XML file that contains the interface for your project with the changes to the imported spec.

  4. Check for the changes to your implementation project.

    For example, if the updated spec adds a new endpoint, the configuration XML for the implementation project has a new flow for the endpoint.

  5. If the spec introduced a new version number, open the pom.xml, and search for the new version of the dependency for the artifactID of the re-scaffolded spec.

Tour the Interface File

After you scaffold your API spec into an interface, examine the scaffolded flows and error handlers for your interface in the UI canvas and configuration XML.

Scaffolded flows in the Canvas

  1. In the Explorer view, open the configuration XML file for your interface.

  2. Click the (Show Mule graphical mode) icon in the activity bar to open the canvas if it doesn’t open automatically.

  3. Click Flow List to navigate through flows:

    Flow List example

  4. In the configuration XML, locate the flows created for the endpoints in your API spec.

    Example Flow 
        <flow name="oas-example-console">
        <http:listener config-ref="oas-example-httpListenerConfig" path="/console/*">
            <http:response statusCode="#[vars.httpStatus default 200]">
                <http:headers>#[vars.outboundHeaders default {}]</http:headers>
            </http:response>
            <http:error-response statusCode="#[vars.httpStatus default 500]">
                <http:body>#[payload]</http:body>
                <http:headers>#[vars.outboundHeaders default {}]</http:headers>
            </http:error-response>
        </http:listener>
        <apikit:console config-ref="oas-example-config" />
        <error-handler>
            <on-error-propagate type="APIKIT:NOT_FOUND">
                <ee:transform doc:name="Transform Message">
                    <ee:message>
                        <ee:set-payload><![CDATA[%dw 2.0
output application/json
---
{message: "Resource not found"}]]></ee:set-payload>
                    </ee:message>
                    <ee:variables>
                        <ee:set-variable variableName="httpStatus">404</ee:set-variable>
                    </ee:variables>
                </ee:transform>
            </on-error-propagate>
        </error-handler>
    </flow>

  5. Review the automatically generated Error Handler components.

    Example Error Handler Component 
    <apikit:console config-ref="oas-example-config" />
    <error-handler>
        <on-error-propagate type="APIKIT:NOT_FOUND">
            <ee:transform doc:name="Transform Message">
                <ee:message>
                    <ee:set-payload><![CDATA[%dw 2.0
output application/json
---
{message: "Resource not found"}]]></ee:set-payload>
                </ee:message>
                <ee:variables>
                    <ee:set-variable variableName="httpStatus">404</ee:set-variable>
                </ee:variables>
            </ee:transform>
        </on-error-propagate>
    </error-handler>

Name Your Interface and Implementation Files

When you import an API spec into an existing integration, Anypoint Code Builder automatically names the configuration XML file based on the API spec name. You can change the file names to something more descriptive, such as based on their function, for example:

  • interface.xml receives all incoming requests to your application and scaffolded flows validate and route requests.

  • implementation.xml provides the backend logic for calls to the interface.

To rename a file, right-click on the file, select Rename, and provide a new name.