Articles in this section

Requirements and best practices for API Management

Kathyana Queeman
Updated

Below are some best practices to follow when creating and managing your APIs.

Before you begin

  1. Only Account owners or Account administrators can create and push APIs to the APIM console.

  2. Your deleted API management resources are kept for at least 30 days based on your account's data retention policy.

API Builder

  1. Design for clarity and usability – Use clear, consistent naming conventions and logical endpoint structures.

  2. Upload your own schema for API requests and responses – Configure your request and responses quickly by uploading your schema directly to API builder.

  3. Ensure data validation and error handling – Validate inputs and return meaningful error messages with appropriate HTTP status codes. You can also customize your errors.

  4. Ensure consistency in responses – Return data in JSON with structured fields.

  5. Test thoroughly – Regularly test your API for functionality, security, and performance to ensure reliability.

  6. Optimized Responses – Return only the necessary data in API responses. Avoid sending unnecessary fields to minimize response size and improve performance.

API Management console

  1. Plans and policies – You can update your plans and policies in the APIM console and publish them to the developer portal.

  2. Rate limiting – Implement rate limiting to prevent API abuse. Define reasonable limits on the number of requests a client can make within a specific timeframe. Add a rate limit policy in the Policy Studio in the APIM console.

  3. Caching – Utilize caching mechanisms to store and reuse responses for common requests. Caching reduces the load on your backend servers and improves response times.

  4. Versioning – Always version your APIs. Versioning helps maintain backward compatibility when you make changes to the API in the future. You can clone, edit, or push a new version of your documentation.

Documentation

  1. Clear Objectives – Define the purpose of the API clearly. Understand what problem it solves or what functionality it provides.

  2. Clear Documentation – Document the API thoroughly, including endpoints, parameters, request/response formats, error codes, and sample requests. Clear documentation helps developers understand how to use the API correctly.

  3. OpenAPI specifications (OAS)

    1. If integrator.io doesn’t automatically create the OAS, you can create it on the Documentation page in the APIM console.

    2. Verify every OAS before publishing it to your developer portal, even if they were created manually.

    3. In the APIM console, if you add or update a plan, change the response schema, or make other changes requiring updating the documentation, you will need to manually update the OAS on the Documentation page.

Monitoring and analytics

  1. Usage Analytics

    1. Implement usage analytics to track how the API is being used. Analyze usage patterns to make informed decisions about future improvements. Specific analytics include:

      1. Response statuses, top endpoints, availability, response time, and API call volume.

  2. Error Tracking – Set up error tracking and monitoring tools to receive alerts for API errors. Proactively address issues to maintain high availability.

Resources

  1. Resources used in a flow should not be directly pushed to your APIM console. Instead, clone the resource and then push it to your manager.

  2. Do not edit your resources after they’ve been created since this can change the API contract for your users.

  3. Add a “Do not modify” warning to your resource’s name so it’s not edited in the future.

    • Notice

      Slack Channel export – Do not modify

Security

Implement strong authentication mechanisms like API keys, OAuth, or JWT tokens. Ensure that only authorized users or applications can access the API endpoints.

Testing

Perform integration tests to validate interactions between different API endpoints. Test common workflows and edge cases to identify potential issues. You can test it:

  • Through Test mode in API builder

  • Through the Developer portal

  • By using Postman

  • By using the Debugging page in the APIM console

Advanced

If you want to promote an API from Sandbox to Production, clone the resource and push the API to the APIM console again. Cloning is not yet available for APIs created through the API builder or for JavaScript APIs. This only applies to cloning resources used to create an API (exports, imports, lookups, etc.).