Introduction to APIs

Welcome to the great world of APIs!

In this article, you will learn:

• What an API is
• What a RESTful API is
• How to work with Tulip's APIs

What is an API?

An API (Application Programming Interface) is a set of protocols that enable different software components to communicate and transfer data.

Developers use APIs to bridge the gaps between small, discrete chunks of code in order to create applications that are powerful, resilient, secure, and able to meet user needs.

There are four key parts to an API:

1. API Client - how you can initiate an API request.
2. API Request - a request for an API to perform an action or provide information back to you.
3. API Server - confirms where the request is coming from, if the request is well-formed, and retrieves or manipulates the requested data.
4. API Response - the response back to you (the client).

API Request

An API request consists of five main pieces:

• Endpoint: This is a dedicated URL that provides access to a specific resource. For example, the /tables endpoint allows you to get all Tulip Tables or create a new Tulip Table.
• Method: This is the type of operation that you would like the API to perform. Since Tulip uses REST APIs, these are limited to GET, PUT, POST, and DELETE.
• Parameters: Variables that are passed to an API endpoint to provide specific instructions for the API to process. Expanding on the previous examples of the /tables endpoint, you can specify a specific table ID through /tables/{tableId}. In addition, we have Queries that can further modify parameters.
• Request Headers: Key-value pairs that provide details about the request, such as its content type or authentication credentials.
• Request Body: Main part of the request that details what data is required to create, update or delete a resource. For example, in the Stations URL, you can craete a new Station and detail out what Station Group it should be part of and which apps it can contain.

API Response

When you successfully put together and send an REST request, the servers respond with the following:

• A status code: Three digit codes that indicate the outcome of an API request.
• Response Headers: Provide additional information about the server's response.
• Response Body: The response body includes the actual data or content the client asked for—or an error message if something went wrong.

Common HTTP status codes include:

200 OK: Indicates that the request has succeeded and the response body contains the requested resource.
404 Not Found: Indicates that the server cannot find the requested resource, often due to a mistyped URL or a resource that has been moved or deleted.
400 Bad Request: Signifies that the server cannot process the request due to a client error, such as invalid syntax or missing required parameters in the request.
500 Internal Server Error: Indicates that the server encountered an unexpected condition that prevented it from fulfilling the request, typically a server-side issue beyond the client’s control.
302 Found (Moved Temporarily): Indicates that the requested resource has been temporarily moved to a different URL. The client should issue another request to the new URL provided in the response header.
401 Unauthorized: Signifies that the request requires user authentication, but the client has not provided valid credentials or has not yet authenticated.

Read more about HTTP error codes here.

What is a RESTful API?

Tulip uses RESTful APIs. Other types of APIs include SOAP, GraphQL, Webbhooks, or gRPC.

A REST API, also known as a RESTful API, is a simple, uniform interface that is used to make data, content, algorithms, media, and other digital resources available through web URLs. REST APIs are the most common APIs used across the web today.

REST APIs make use of four key methods:

1. GET: This method allows for the server to find the data you requested and sends it back to you.
2. PUT: If you perform the PUT request, then the server will update an entry in the database.
3. POST: This method permits the server to create a new entry in the database.
4. DELETE: This method allows the server to delete an entry in the database.

How to work with Tulip's API

Read through the following articles to begin using and testing APIs with Tulip:

• What are Connectors?
• How to Create and Configure an HTTP Connector Function
• Setting up a Tulip API

Did you find what you were looking for?

You can also head to community.tulip.co to post your question or see if others have faced a similar question!