In software development, APIs enable different applications to communicate and interact seamlessly. An API, short for Application Programming Interface, acts as a bridge allowing applications to access the features, data, or services of an operating system, application, or platform.
What is an API?
APIs represent a set of functions and procedures allowing the creation of applications that access the features or data of an operating system, application, or other services. Essentially, an API provides a standardized way for applications to make requests and receive responses from another system or application, most commonly between backend and frontend applications.
It's important to note that APIs are not limited to handling data. While data retrieval and manipulation are common use cases, APIs can serve various purposes based on the system they interact with. They can facilitate authentication, execute actions, and retrieve information.
In this article, we will focus on creating a Postman collection for your Platformatic API, which will simplify the testing process. By harnessing the power of Postman collections, you can save all your requests, organize them and make them more accessible to other developers who wish to integrate with your APIs.
đź’ˇ
A quick intro to PlatformaticÂ
Platformatic is a powerful framework that aims to simplify and streamline API development, allowing developers to build efficiently and scale APIs. The primary goal of Platformatic is to simplify API development by eliminating friction from the daily workflow of backend developers. It provides a series of open-source tools specifically designed to build APIs efficiently. Whether starting a new project or working on an existing one, Platformatic aims to make the setup process effortless, allowing you to have a production-ready environment in no time.
Platformatic DB is one of our tools that address the common task of creating Create-Read-Update-Delete (CRUD) APIs. With it, developers can generate both OpenAPI and GraphQL schemas directly from their databases without writing a single line of code. Its flexibility sets Platformatic DB apart from similar tools – it is fully customizable using Node.js and Fastify plugins. With Platformatic DB, developers can easily create a REST API based on their existing database schema.
Platformatic empowers developers by simplifying and streamlining API development, ultimately allowing developers to focus on creating robust and innovative APIs.
Prerequisites
Before diving into the Platformatic DB, ensure you have the following installed on your machine
To create a new Platformatic project using the Platformatic CLI:
1. Open your terminal and run the following command:
npm create platformatic@latest
2. The CLI will initiate an interactive command-line tool to guide you through the project setup process. For this guide, select the following:
- Which kind of project do you want to create? => DB
- Where would you like to create your project? => quick-start
- Do you want to create default migrations? => Yes
- Do you want to create a plugin? => Yes
- Do you want to use TypeScript? => No
- Do you want to install dependencies? => Yes (this may take a while)
- Do you want to apply the migrations? => Yes
- Do you want to generate types? => Yes
- Do you want to create the GitHub action to deploy this application to Platformatic Cloud dynamic workspace? => No
- Do you want to create the GitHub action to deploy this application to Platformatic Cloud static workspace? => No
Once the wizard completes, you will have a Platformatic app project created in the "quick-start" folder. It will include sample migration files and a sample plugin script.
Start your API server
To navigate to the project directory using the VS Code terminal, you can use the following command:
cd quick-start
This command will change your current directory to the quick-start directory, where your Platformatic project is located. Run the following command to start your API server:
npm start
Congratulations- your Platformatic DB is now up and running!
Using the REST API interface
Platformatic DB automatically maps your SQL database to REST and GraphQL API; in this case, we use a default application: a catalog of movies.
To interact with the REST interface of your API, you can use cURL or any other HTTP client. Here's an example using cURL to store one of our favourite movies.
Create a new movie
curl -X POST -H "Content-Type: application/json" \
-d "{ \"title\": \"The Little Mermaid\" }" \
http://localhost:3042/movies
You should receive a response from your API like this:
{"id":1,"title":"The Little Mermaid"}
To get all movies and verify everything worked correctly, run:
curl http://localhost:3042/movies
Setting Up Postman with Platformatic
To effectively test an application built with Platformatic, you can leverage the power of Postman, a popular API development and testing tool. In this section, we will explore how you can utilize Postman to interact with your Platformatic application using collections.
To get started, ensure that you have Postman installed on your machine. You can download Postman for free (it is available for Windows, macOS, and Linux platforms).
Sending your first request
Postman simplifies the process of creating and sending API requests. Postman enables users to avoid using the command line or writing any code. Instead, you can use Postman's graphical user interface (GUI) to create and send new requests easily. You can even use the cURL snippets provided earlier as a reference.
If you're new to Postman, let's go through the process step by step:
1. Sign in to Postman
Launch Postman on your machine.
If you don't have an account, you can create one or sign in using your preferred method.
2. Create a new workspace
Navigate over to workspaces and create a new workspace:
Postman Collections
Postman collections are a convenient way to save and manage your requests that work just like folders. As you use Postman more frequently, relying on the history section alone can become time-consuming. A collection serves as a container for related requests and allows you to group them into folders based on their functionality or resource. By providing descriptions and examples for each request, you can enhance the documentation and clarity of your collection for other developers also using it. Postman allows you to import previously exported data, which it calls "collections", to save time by reusing the Postman configuration that was done in the past.
Creating your first collection
To create a new collection:
Click on the "Collections" tab in the Postman sidebar.
Click the + button to create a new collection and provide a proper name.
Optionally, you can create folders within the collection to further organize your requests.
With your collection created, you can now start adding requests to it.
Testing a route
We can make a test GET request to our API to check if our Postman is configured correctly with our CRUD API. Inside the collection, we create a new request that makes a GET request to our API to see the movies stored in the API. The URL - http://127.0.0.1:3042/movies is copied from our terminal after running the npm start command.
A Status: 200 OK indicates a successful request.
Creating a Postman Collection
Instead of manually creating each request, you can import the OpenAPI specification generated by Platformatic DB to streamline the process.
Here's how to import data into Postman using our Platformatic OpenAPI documentation:
1. Head over to this published collection, where we have our sample API documentation.
2. Click on the Run in Postman button on the top right corner of the page and run in any suitable environment.
3. Import the collection into your workspace.
Once the data is imported, you can proceed to make a POST request to our API URL, which in this case is http://127.0.0.1:3042/movies. Ensure that the request body contains the required data in raw JSON format. Importing data into Postman saves time and effort, allowing you to focus on testing and interacting with your application.
Sharing A Collection
Once you've created a collection in Postman, you have several options for sharing it with others. Let's explore the different methods:
1. Publish a Run in Postman button: By publishing a Run in Postman button, you can generate a snippet of code that others can embed in their own applications or documentation. This allows them to run your collection directly from their environment.
2. Collaborating with others: Invite other users to collaborate on your collection by selecting the "More actions" icon next to the collection name and choosing the "Share" option. This enables seamless collaboration, allowing team members to access and work on the collection together, and keeps the collections up-to-date and easily accessible for everyone involved.
3. Sharing as a JSON file or URL: If you prefer not to add people to your team but still need to share Postman collections, you can export the collection as a JSON file. This file can then be shared with others who can import it into their own Postman instance. Additionally, you can generate a URL that points to the JSON data of your collection. By sharing this URL, others can import the collection directly into Postman, making it easy to distribute and collaborate on collections without the need for team membership.
With these sharing options, you can effectively distribute and collaborate on your Postman collections, allowing others to seamlessly access and utilize your APIs.
Wrapping up
In this article, we explored how to create a Postman collection from the API generated by Platformatic DB.
Platformatic simplifies API development and management at scale, allowing backend engineers to focus on delivering business demands without the need for repetitive infrastructure building. Developers can streamline API testing, documentation, and collaboration by integrating Postman into this workflow.
We saw how with Platformatic, you can efficiently develop and run APIs, while Postman provides a user-friendly interface for sending API requests and organizing them into collections. This combination enhances productivity and simplifies the process of creating, testing, and sharing APIs.
To further explore the capabilities of Platformatic DB and discover additional functionalities, check out our documentation.
