What Is an API (Application Programming Interface)?

Confluent Server includes a fully managed, cloud-native distribution of Apache Kafka, the popular open-source data streaming platform. Here is an example cURL command to Confluent Server’s REST API that creates a so-called “Kafka topic” (see https://developer.confluent.io/learn-kafka/apache-kafka to learn more about Apache Kafka, including what Kafka topics are):

curl --silent -X POST -H "Content-Type: application/json" \
--data '{"topic_name": "my-cool-topic"}' \
-u chuck:chuck-password \
http://localhost:8090/kafka/v3/clusters/7cteo6omRwKaUFXj3BHxdg/topics | jq

Here are a few things to notice about the cURL command:

• We are using the HTTP “POST” method. This makes sense because we are creating a resource (a Kafka topic)
• --silent
  • This just mutes cURL’s progress meter and error messages so you can focus on the response payload
• -X is just a shortcut for --request
• -H is just a shortcut for --header
• -u is just a shortcut for --user
• We pipe the output to th jq command to make it look prettier

The Confluent server could respond with a 401 status code to indicate the user’s authentication failed, a 403 status code to indicate the user is not authorized to create the topic, or a 200 to indicate success. Here is the response JSON payload upon success:

{
	"kind": "KafkaTopic",
	"metadata": {
		"self": "http://localhost:8090/kafka/v3/clusters/7cteo6omRwKaUFXj3BHxdg/topics/my-cool-topic",
		"resource_name": "crn:///kafka=7cteo6omRwKaUFXj3BHxdg/topic=my-cool-topic"
	},
	"cluster_id": "7cteo6omRwKaUFXj3BHxdg",
	"topic_name": "my-cool-topic",
	"is_internal": false,
	"replication_factor": 0,
	"partitions": {
		"related": "http://localhost:8090/kafka/v3/clusters/7cteo6omRwKaUFXj3BHxdg/topics/my-cool-topic/partitions"
	},
	"configs": {
		"related": "http://localhost:8090/kafka/v3/clusters/7cteo6omRwKaUFXj3BHxdg/topics/my-cool-topic/configs"
	},
	"partition_reassignments": {
		"related": "http://localhost:8090/kafka/v3/clusters/7cteo6omRwKaUFXj3BHxdg/topics/my-cool-topic/partitions/-/reassignment"
	}
}

This indicates the resource was successfully created and gives detailed information about it.

The entire API reference is here, including many cURL examples: https://docs.confluent.io/platform/current/kafka-rest/api.html

Go to https://lucasconstantino.github.io/graphiql-online/ to play hands-on with a graphQL API.

Here is an example query that you can input into the GraphQL playground:

query{
countries(filter:{code:{regex:".*A.*"}}){
currency
code
name
continent{
  name
}
  }
  languages (filter:{code:{regex:".*r"}}) {
native
name
code
  }  
}

This example illustrates how GraphQL gives the client the power to decide what data they want the server to return. With a REST API, making a GET request to a /countries endpoint would return a lot of information the client doesn’t necessarily need, and it would be up to the client to parse through the response.

In addition, GraphQL empowers the client to choose data they want from a variety of resources in a single request. In this example, we also see that the client has requested information about languages. With a RESTful architecture, the client would have to make two requests, one to /countries and another to /languages.

Here are a few things to notice about the query:

• The query is defined with the “query” keyword within curly braces {}
• A filter can be applied so that only a subset of data is returned to the client E.g. for (filter:{code:{regex:".*A.*"}}), we select only the countries whose country code contains an “A” using regular expressions.

The GraphQL web editor, called GraphiQL, is sending an HTTP request to a real GraphQL endpoint. Here’s what an equivalent cURL command looks like (note the escape backslashes for double quotes and the lack of newlines in the query value):

curl -s -X POST -H "Content-Type: application/json" \
--data '
{"query": "query{countries(filter:{code:{regex:\".*A.*\"}}){currency
code name continent{name}}languages(filter:{code:{regex:\".*r\"}}
{native name code}}" }' [https://countries.trevorblades.com/
(https://countries.trevorblades.com/) | jq

Next, explore the API on your own. It’s especially helpful to use Ctrl+Space to take advantage of auto-complete. Also don’t forget to explore the docs panel on the upper right. These docs are automatically generated from GraphQL’s type system (yay schemas and auto generated documentation!).

# Set user profile data
curl -X POST \
-H “Content-Type: application/json” -H “Authorization: Bearer my-super-secret-token” \
--data ‘{

"profile": {

   "status_text": "riding a train",
"status_emoji": ":mountain_railway:",
"status_expiration": 1532627506,
"first_name": "John",
"last_name": "Smith",
"email": "john@smith.com",
"fields": {

   "Xf06054BBB": {
"value": "Barista",
    "alt": "I make the coffee & the tea!"
}
}
}
}’ https://slack.com/api/users.profile.set?user=W1234567890 | jq

The JSON data payload is taken straight from the example in Slack’s documentation. Notice the endpoint /api/users.profile.set is an action rather than a resource. Here just a few other action-oriented RPC endpoints related to users:

• users.profile.get
• users.deletePhoto
• users.setPhoto
• users.setActive

Slack API documentation pages for their endpoints (called “methods”, which makes sense for RPC):

• https://api.slack.com/methods

Here is a simple Python program that uses the API provided by the json library to serialize a Python dictionary into a json file.

import json

my_dictionary= {“my-key”:[1,2,3]}
with open(“my-file.json”, “w”) as f:
  json.dump(my_dictionary, f)

Here are a few things to notice:

• import json
  • This is where we import the library. Every language provides ways to import libraries.
• json.dump(my_dictionary, f)
  • We can research the library’s official API documentation to find the functions and objects we need for our program.
  • In this case, we find that the dump command does what we want — it takes a Python object and serializes it into JSON file format.
  • The API specifies that dump has two required positional arguments — first, the object to be serialized, and second, a file writer object to write the JSON data to a file.
• The important point is that we can use the dump function in our program without knowing at all how it is implemented.

Here are some of the most popular tools for developing and using APIs:

Search hubs for APIs others have made:

• https://app.swaggerhub.com/search by SmartBear
• https://www.postman.com/explore by Postman

Tools to interact with APIs:

• https://swagger.io
• Interactive online API editor demo that models a pet store REST API with Open API: https://editor.swagger.io/
• https://postman.com
• https://insomnia.rest/ – API development tool by Kong, Inc.
• https://httpie.io/ – httpie is a really great, modern alternative to cURL
• https://httpie.io/docs/cli/examples – examples that you can run interactively on https://httpie.io/cli/run

Popular frameworks for developing web APIs:

• Python
• FastAPI https://fastapi.tiangolo.com/
• Flask https://flask.palletsprojects.com/en/2.1.x/
• Django https://www.djangoproject.com/
• Java
• SpringBoot https://spring.io/projects/spring-boot
• Really helpful tool to initialize new projects: https://start.spring.io/
• Quarkus https://quarkus.io/
• Go
• Gin https://gin-gonic.com/
• Gorilla http://www.gorillatoolkit.org/
• GraphQL Code Generator https://www.graphql-code-generator.com/
• Define your schema and generate frontend client code and backend server code
• OpenAPI specification https://spec.openapis.org/oas/v3.1.0
• Provides a language-agnostic specification that allows you to declare an API in a JSON or YAML document file (usually called openapi.yml, swagger.yaml, or similar)
• Use Swagger Codegen or OpenAPI Generator to take the OpenAPI document file and generate REST API server and client code, as well as documentation, in the language or framework of your choice.
• AsyncAPI specification https://www.asyncapi.com/
• In the same family as OpenAPI, but focused on asynchronous, event-driven APIs rather than synchronous request/response APIs
• Like OpenAPI, you create an API in a YAML document file and use tools to generate code and documentation