Skip to main content
Redhat Developers  Logo
  • Products

    Featured

    • Red Hat Enterprise Linux
      Red Hat Enterprise Linux Icon
    • Red Hat OpenShift AI
      Red Hat OpenShift AI
    • Red Hat Enterprise Linux AI
      Linux icon inside of a brain
    • Image mode for Red Hat Enterprise Linux
      RHEL image mode
    • Red Hat OpenShift
      Openshift icon
    • Red Hat Ansible Automation Platform
      Ansible icon
    • Red Hat Developer Hub
      Developer Hub
    • View All Red Hat Products
    • Linux

      • Red Hat Enterprise Linux
      • Image mode for Red Hat Enterprise Linux
      • Red Hat Universal Base Images (UBI)
    • Java runtimes & frameworks

      • JBoss Enterprise Application Platform
      • Red Hat build of OpenJDK
    • Kubernetes

      • Red Hat OpenShift
      • Microsoft Azure Red Hat OpenShift
      • Red Hat OpenShift Virtualization
      • Red Hat OpenShift Lightspeed
    • Integration & App Connectivity

      • Red Hat Build of Apache Camel
      • Red Hat Service Interconnect
      • Red Hat Connectivity Link
    • AI/ML

      • Red Hat OpenShift AI
      • Red Hat Enterprise Linux AI
    • Automation

      • Red Hat Ansible Automation Platform
      • Red Hat Ansible Lightspeed
    • Developer tools

      • Red Hat Trusted Software Supply Chain
      • Podman Desktop
      • Red Hat OpenShift Dev Spaces
    • Developer Sandbox

      Developer Sandbox
      Try Red Hat products and technologies without setup or configuration fees for 30 days with this shared Openshift and Kubernetes cluster.
    • Try at no cost
  • Technologies

    Featured

    • AI/ML
      AI/ML Icon
    • Linux
      Linux Icon
    • Kubernetes
      Cloud icon
    • Automation
      Automation Icon showing arrows moving in a circle around a gear
    • View All Technologies
    • Programming Languages & Frameworks

      • Java
      • Python
      • JavaScript
    • System Design & Architecture

      • Red Hat architecture and design patterns
      • Microservices
      • Event-Driven Architecture
      • Databases
    • Developer Productivity

      • Developer productivity
      • Developer Tools
      • GitOps
    • Secure Development & Architectures

      • Security
      • Secure coding
    • Platform Engineering

      • DevOps
      • DevSecOps
      • Ansible automation for applications and services
    • Automated Data Processing

      • AI/ML
      • Data Science
      • Apache Kafka on Kubernetes
      • View All Technologies
    • Start exploring in the Developer Sandbox for free

      sandbox graphic
      Try Red Hat's products and technologies without setup or configuration.
    • Try at no cost
  • Learn

    Featured

    • Kubernetes & Cloud Native
      Openshift icon
    • Linux
      Rhel icon
    • Automation
      Ansible cloud icon
    • Java
      Java icon
    • AI/ML
      AI/ML Icon
    • View All Learning Resources

    E-Books

    • GitOps Cookbook
    • Podman in Action
    • Kubernetes Operators
    • The Path to GitOps
    • View All E-books

    Cheat Sheets

    • Linux Commands
    • Bash Commands
    • Git
    • systemd Commands
    • View All Cheat Sheets

    Documentation

    • API Catalog
    • Product Documentation
    • Legacy Documentation
    • Red Hat Learning

      Learning image
      Boost your technical skills to expert-level with the help of interactive lessons offered by various Red Hat Learning programs.
    • Explore Red Hat Learning
  • Developer Sandbox

    Developer Sandbox

    • Access Red Hat’s products and technologies without setup or configuration, and start developing quicker than ever before with our new, no-cost sandbox environments.
    • Explore Developer Sandbox

    Featured Developer Sandbox activities

    • Get started with your Developer Sandbox
    • OpenShift virtualization and application modernization using the Developer Sandbox
    • Explore all Developer Sandbox activities

    Ready to start developing apps?

    • Try at no cost
  • Blog
  • Events
  • Videos

Applying API Best Practices in Fuse

January 19, 2017
Christina Lin
Related topics:
Java
Related products:
Red Hat Fuse

Share:

    API plays a huge part in modern integration architecture design, a good design will allow your application to thrive, a bad design will end up on the cold stone bench and eventually vanishes. :(

    Well, to avoid this tragedy from happening to our APIs, there are certain guidelines that we might want to consider to follow. I know there are many debates out there on the best practice of API design, and I don't think it will ever end. It really depends on many different factors; mostly dominated by the size and complexity of the integration solution, and the company culture. And many of them relate to how to manage it instead of designing it. (Of course, there are many others like API security, how to do versioning and all these sorts of things. These relate more closely to API management, that I will not cover in this post.)

    This is what I think makes a good API:

    1. Intuitive -  It must be easy to understand and can be used without documentation.
    2. Stable - Not only should it run but it should also have good performance too.
    3. Demands - Creating useful functionality, no matter how nicely you document your API or how easy it is to use, if people don't need it, they won't call it.

    The Stability is mostly dependent on how robust your code is, the DEVOPS process, how the IT infrastructure is built and so on. The Demands are a much harder question to answer, so I am going to focus on the Intuitive. Here are just couple of best practices of that I think that can make APIs more intuitive, and how it's done in Camel. (RESTFul API, strictly speaking, the technology the most people use is the standard.)

    • Simply but concrete naming for the URI.
      • Common rules, use nouns instead of verbs, that describe the content the API is providing, such as customer, account, and product etc.  In Camel the place to define it is in the REST DSL, it allows the developer to define REST services in its application. Define the name of the API in the URI and have several layers of API description.
               <get uri="customer/{customerid}">
                 <to uri="direct:getCustomerinfo"/>
               </get>
               <get uri="product/{id}">
                 <to uri="direct:productInventory"/>
               </get>
               <get uri="account/profile/{acctid}">
                 <to uri="direct:getprofile"/>
               </get>

     

      • From the architectural standpoint, one of the good things about Camel and Fuse/Fuse Integration Service, is you naturally create these independent chunks of service, that either connects to a datasource (or multiple if you want, but that does not quite fit in the spirit of doing microservices) and then becomes a microservice. Or you can use it to create a service that composes/orchestrates APIs for the consumer.

            Camel and Fuse/Fuse Integration Service

    • Use HTTP Method for CRUD if possible:
      • READ -> GET
      • CREATE -> PUT
      • UPDATE -> POST
      • DELETE -> DELETE
      • Instead of creating four different names with the verbs that we normally do in webservice back in the day, take advantage using the HTTP method, which is already there and the HTTP header actually maps to different operations that you need to do. In Camel DSL, it is very simple to define it.
      • Not only does it eliminate the need for the whole team to agree upon the naming of the actions, since it's a globally recognized standard, consumers will find it easier to understand.
    • Make the most out of HTTP Errors,
      • Wrapping your own error is good, but think about this, when a consumer gets a response from the API, what is the first content it gets? Instead of processing the entire payload, (which is not restricted to error, there are several successful status codes too) the consumer receives the HTTP response header.
      • Here is the list of HTTP status codes; some are commonly used in RESTApi along with a few common ones for RESTFul API.
    HTTP Code HTTP Methods Description (From Wiki page)
    200 GET, DELETE Standard response for successful HTTP requests. The actual response will depend on the request method used.
    201 Created PUT, POST The request has been fulfilled, resulting in the creation of a new resource.
    202 Accepted POST, PUT, DELETE The request has been accepted for processing, but the processing has not been completed.
    400 Bad Request GET, POST, PUT, DELETE The server cannot or will not process the request due to an apparent client error
    401 Unauthorized GET, POST, PUT, DELETE Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided.
    403 Forbidden GET, POST, PUT, DELETE The request was a valid request, but the server is refusing to respond to it.
    404 Not Found GET, POST, PUT, DELETE The requested resource could not be found.
    408 Request Timeout GET, POST, PUT, DELETE The server timed out waiting for the request.
    409 Conflict PUT, PUT, DELETE Indicates that the request could not be processed because of conflict in the request.
    500 Server Error GET, POST, PUT, DELETE A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.
    503 Service Unavailable GET, POST, PUT, DELETE The server is currently unavailable (because it is overloaded or down for maintenance). Generally, this is a temporary state.
      • In Camel, you can set the value in the header to return the HTTP status code.
              <setHeader headerName="camelhttpresponsecode">
                  <constant>400</constant >
              </setHeader>

     

    • Setting the right granularity of data and using the common data format:
      • I don't believe in the ONE SIZE FITS ALL data model when it comes to providing information to various consumers, the amount of information can be shown on a mobile device screen, a smart watch or a desktop computer is definitely different.
      • Camel has the capability for you to automatically transform the data from POJO into the format you want by specifying the output, or you can simply marshal with various Camel supported data formats or do a little extra processing with the Data Mapper transform component.

    The binding mode:

                   <restConfiguration  bindingMode="json" />

     

    Binding Mode Description
    off Binding is turned off. This is the default option.
    auto Binding is enabled and Camel is relaxed and supports json, XML, or both if the needed data formats are included in the classpath. Notice that if for example, camel-jaxb is not on the classpath, then XML binding is not enabled.
    json Binding to/from json is enabled and requires a json capable data format on the classpath. By default, Camel will use json-jackson as the data format. See the INFO box below for more details.
    xml Binding to/from XML is enabled and requires camel-jaxb on the classpath. See the INFO box below for more details.
    json_xml Biding to/from json and xml is enabled and requires both data formats to be on the classpath. See the INFO box below for more details.

    Or DataFormat Marshaling (Don't forget to add the dependency of the converting libraries).

             <marshal ref="transform-json">
                <json library="Jackson"/>
             </marshal>

     

    Or Data Mapper transform (Dozer).

    See my previous posts

    • Automatically generated documentation:
      • One of the nice handy little tricks when doing API in Camel with REST DSL, you can simply integrate it with Camel swagger java components. It will expose the API in swagger format.
      • In Camel, don't forget to first to add the dependency in your maven pom.
           <dependency>
               <groupId>org.apache.camel</groupId>
               <artifactId>camel-swagger-java</artifactId>
               <version>x.x.x</version>
           </dependency>

     

    And inside the Camel context, when setting up the rest configuration, simply add the API related configuration into it.

               <restConfiguration apiContextPath="api-docs" bindingMode="json"
                     component="servlet" contextPath="/demos">
                      <apiProperty key="cors" value="true"/>
                      <apiProperty key="api.title" value="Healthcare demo clinical API"/>
                      <apiProperty key="api.version" value="1.0.0"/>
                </restConfiguration>

     

    In summary, this diagram maps to Camel and its best practices.

    Diagram maps to Camel and its best practices

    Thanks!

    Last updated: August 29, 2023

    Recent Posts

    • GuideLLM: Evaluate LLM deployments for real-world inference

    • Unleashing multimodal magic with RamaLama

    • Integrate Red Hat AI Inference Server & LangChain in agentic workflows

    • Streamline multi-cloud operations with Ansible and ServiceNow

    • Automate dynamic application security testing with RapiDAST

    Red Hat Developers logo LinkedIn YouTube Twitter Facebook

    Products

    • Red Hat Enterprise Linux
    • Red Hat OpenShift
    • Red Hat Ansible Automation Platform

    Build

    • Developer Sandbox
    • Developer Tools
    • Interactive Tutorials
    • API Catalog

    Quicklinks

    • Learning Resources
    • E-books
    • Cheat Sheets
    • Blog
    • Events
    • Newsletter

    Communicate

    • About us
    • Contact sales
    • Find a partner
    • Report a website issue
    • Site Status Dashboard
    • Report a security problem

    RED HAT DEVELOPER

    Build here. Go anywhere.

    We serve the builders. The problem solvers who create careers with code.

    Join us if you’re a developer, software engineer, web designer, front-end designer, UX designer, computer scientist, architect, tester, product manager, project manager or team lead.

    Sign me up

    Red Hat legal and privacy links

    • About Red Hat
    • Jobs
    • Events
    • Locations
    • Contact Red Hat
    • Red Hat Blog
    • Inclusion at Red Hat
    • Cool Stuff Store
    • Red Hat Summit

    Red Hat legal and privacy links

    • Privacy statement
    • Terms of use
    • All policies and guidelines
    • Digital accessibility

    Report a website issue