What are API collections? How to create it

Ready to create your first API collection? Don't worry, it's easier than you might think! Let's walk through the process together, step by step.

1. Prerequisites

Before we dive in, make sure you have:

1. A Workato account with access to the API Platform

2. A project created (or an existing one you want to use)

3. For API recipe collections: A folder with one or more API recipes

4. For API proxy collections: An HTTP connection to forward requests

Got all that? Great! Let's get started.

2. Step-by-Step Guide

1. Accessing the API Collections Page
First things first, let's navigate to where the magic happens:

1. Log into your Workato account

2. Go to the Platform menu

3. Click on API Platform

4. Select API Collections

You're now on the API collections page. This is where all your collections will live.

2. Selecting Collection Type
Time to choose your flavor:

1. Click on the "New Collection" button

2. You'll see three options: API Proxy Collection, API Recipe Collection, or AI Gateway Collection

3. Select the type that fits your needs (remember our discussion on types from earlier?
   
   

3. Configuring Endpoints

Now for the fun part - setting up your endpoints:
For API Proxy Collections:

1. Choose an HTTP connection to forward requests to

2. Select a configuration type (Import OpenAPI Spec or Manual)

3. If importing, upload your OpenAPI file or enter a URL

4. Select the endpoints you want to include

For API Recipe Collections:

1. Choose to use existing recipes or import an OpenAPI Spec

2. If using recipes, select the folder containing your API recipes

3. If importing, upload your OpenAPI file or enter a URL

4. Customize your endpoints as needed

For AI Gateway Collections:

1. Choose to use existing recipes or import an OpenAPI Spec

2. Follow the same steps as API Recipe Collections for your chosen method

Pro Tip: When customizing endpoints, pay attention to the endpoint name, path, and HTTP method. These are crucial for how your API will be accessed.

4. Creating and Testing Requests—No Code Needed

You might be wondering: “Do I need to write scripts or use the command line to interact with my APIs?” Good news—absolutely not! Modern API platforms make it easy for anyone to create, send, and test requests without a single line of code.

Here’s how it works:

• Use a visual interface to build your API requests by choosing the request type (like GET or POST), filling in any necessary parameters or headers, and defining the endpoint path—just point, click, and type.

• Hit “Send” (or your platform’s equivalent), and the response from your data source appears instantly in the workspace.

• You can tweak settings, view results, and experiment with different inputs, all from your browser. No terminal gymnastics required.

This user-friendly approach means you can validate endpoints, explore data, and see how your APIs behave—whether you’re a seasoned developer or just getting your feet wet.

5. Setting Collection Details

Almost there! Let's give your collection an identity:

1. Enter a name for your collection (make it descriptive!)

2. Assign a version (this helps with managing updates later)

3. Add a description (optional, but helpful for your team)

4. Select the project this collection belongs to
   
   

6. Activating Endpoints

The final touch - bringing your endpoints to life:

1. After creating your collection, you'll see an overview of all endpoints

2. By default, new endpoints are inactive

3. To activate an endpoint, simply toggle the "Inactive" button to "Active"

4. Repeat for all endpoints you want to make available

And voilà! You've just created your very own API collection. Pat yourself on the back – you're now an API organization pro!

Remember, creating a collection is just the beginning. Don't forget to manage access, monitor usage, and keep your collection updated as your needs evolve.

7. Authorization Made Simple

Before you open your API doors to the world, you'll want to make sure only the right folks get in. That’s where authorization comes in! APIs support a variety of authorization methods, each designed to keep your data secure while making life easier for legitimate users.

Here’s a quick rundown of the most common API authorization methods, plus how to set them up in minutes:

• API Keys: This is the classic—just generate a unique key for each user or application. Then pop that key into a request header or parameter and you’re all set. Many platforms, like Stripe or Google Maps, rely on this super simple approach.

• OAuth 2.0: When you want fine-grained, delegated access (think: “Log in with Google” buttons), OAuth 2.0 is your friend. Set it up by registering your application with the provider (like Microsoft or GitHub), grab your client ID and secret, and follow their quick-start wizard to get tokens for user access.

• Bearer Tokens: Think of these as digital hall passes. Once a user logs in (often via OAuth2), they’re issued a token, which they include in the Authorization header of API calls. This method is robust and flexible—great for modern web apps.

• Basic Auth: For quick-and-dirty security (and for internal tools or testing), this method encodes a username and password in the request header. Just remember, it’s best paired with HTTPS for safety.

• Client Certificates: For extra-tight security, some APIs use client SSL certificates. Here you’ll need to generate, install, and manage certs for each approved user or device.

• Custom Solutions: Some APIs roll out their own methods, using custom tokens, signed requests, or even HMAC signatures. Always check the docs for specifics!

Quick Tip: Save yourself from credential headaches by using environment variables or secret management tools whenever possible—this keeps passwords and keys out of your codebase and helps your team collaborate securely.

No matter which method you choose, setting up authorization usually boils down to: selecting your preferred method, entering a few details (like keys or credentials), and verifying the connection—often as simple as filling a form or toggling an option.

8. Managing and Reusing Authorization Details

Let’s talk about handling authorization—because scrambling for API keys every time you make a request is no one’s idea of fun.

Rather than entering credentials for each endpoint, you can streamline the process by centralizing your authorization settings within your API collection. Here’s how to make it painless (and secure):

• Set Authorization at the Collection Level: Define your preferred authentication method (like OAuth, API key, or JWT) directly in your collection’s settings. This way, all endpoints within that collection inherit these details automatically.

• Leverage Environment Variables: Store sensitive information (such as tokens, credentials, or secrets) in environment variables. This approach keeps your actual credentials from being hard-coded in requests and makes switching between dev, staging, and production environments a breeze.

• Customize When Needed: If an individual endpoint requires a different authorization method or specific credentials, you can override the collection settings just for that endpoint.

• Keep It Safe and Efficient: By managing authorization in one place and reusing variables, you reduce the risk of mistakes, eliminate repetitive entry, and improve team collaboration.

This setup not only saves time but also helps keep your API requests consistent and secure as your project grows. Next up: managing your new API collection like a champ and unlocking even more features!

Crafting API Documentation with Markdown

Now that your endpoints are live, it's time to make them shine with clear documentation. Markdown is your best friend here—it lets you create clean, readable documentation without fuss, so your developers (and your future self) will thank you.

Why Use Markdown?

• Easy Formatting: Markdown makes it simple to add headers, lists, code blocks, and even tables—perfect for structuring endpoint details and usage examples.

• Live Examples: Drop in request/response examples or curl commands to show how your API works in practice.

• Quick Edits: Change details on the fly—no complicated formatting tools required.

• Rich Readability: The result is documentation that's both easy to read and visually organized.

How to Use It

When writing your API documentation, consider these essentials:

• Add a high-level introduction at the top so readers know what they're working with.

• List endpoints using Markdown headers and bullet points.

• For each endpoint, include method, path, parameters, and authentication requirements.

• Use code blocks for example requests and responses, like so:

  curl -X GET "https://api.example.com/v1/users" -H "Authorization: Bearer token"

  {
    "id": 123,
    "email": "user@example.com"
  }

• Highlight optional and required fields clearly using bold or italics.

Pro Tip: Tools like GitHub, GitLab, and Bitbucket render Markdown beautifully, so your docs look polished wherever they're shared.

Clear, friendly documentation means fewer headaches and smoother integrations. Take the time to make your docs welcoming and easy to follow—your team (and your users) will be glad you did!

Generating Sample Test Data

Need to put your shiny new API collection through its paces? Generating realistic test data is key for troubleshooting, validation, and simulating real-world use cases—without any risk to your production systems.

Here are a few handy ways to create fake test data for your APIs:

• Online Data Generators: Free tools like Mockaroo and RandomUser.me let you create a variety of datasets on demand, from user profiles to custom records. Simply specify the fields and formats you need, then download or pipe them directly into your tests.

• Open Source Libraries: If you prefer to keep things scriptable, libraries such as Faker (available for Python, JavaScript, and more) and Chance.js make it easy to generate random data within your test scripts or recipes.

• Custom Scripts: Feeling adventurous? You can always write your own logic to build test data tailored to your business logic (great for complex, structured data).

Pro Tip: Using fabricated data not only protects real user information but also helps ensure your API behaves consistently—even under unusual or edge-case scenarios.

Armed with a stash of fake data, you’re ready to run comprehensive tests and catch tricky bugs before they ever reach production.