Introduction to APIs

What are APIs?

As a human being, you interact with software, such as applications and websites, through a UI, a User Interface. The UI exposes text, buttons, and other control elements that allow you to communicate with the software. Similarly, an API – or  Application Programming Interface – is a way for two pieces of software to talk to each other. One application provides the API, and another consumes it.

The term API applies to a variety of software interfaces. In the more specific context of the BASF Developer Portal and also most commonly, an API is a way for two systems to communicate over a network – the corporate Intranet or the public Internet.

These APIs utilize HTTP,  the same protocol that browsers use to fetch web pages. In the browser, you can enter a URL, click on links or type information in forms, and the web server returns a human-readable page created in HTML. With APIs, the exchange of information takes place in machine-readable structured formats instead. The most common format used for APIs today is JSON, but XML is also widely used.

To emphasize the fact that an API can be considered a product with specific functionality, it is common to talk about "API Products." Throughout this portal and the documentation, you may find both terms "API" and "API Product" used with the same meaning.

Why are APIs useful?

As a software developer, APIs allow you to extend the applications you create with additional functionality that you do not have to implement yourself. Therefore, the development of new applications becomes easier and more powerful at the same time; hence productivity rises.

You can also implement use cases that depend on external datasets without having to include the data in your application. This way, your users can always work with the latest version from the server. Thus, APIs are a better, more streamlined way to exchange information, compared to alternatives like screen-scraping or exporting and importing CSV files.

Even if you are not a developer or a meager qualified one, APIs are useful, too. You can, for example, include data from APIs in Excel sheets. You can also build automation with integration platforms or low-/no-code tools. APIs, both public APIs, as well as those deployed within the enterprise, can facilitate digital transformation and new business models. That makes knowledge about using APIs a valuable skill.

How can I get started with APIs?

The first thing to get started in your API journey is to learn and understand the basics of APIs. The document you're reading right now is an excellent place to start.

The next thing is finding an API with which you want to work. Many divisions of the BASF Group offer APIs and you can find all published APIs in a catalog on this developer portal.

Outside of BASF, many websites, software-as-a-service vendors, and other organizations offer APIs and have their own developer portals. You can typically find them by following a link called API or Developer from their home page. Some websites collect available public APIs, the largest being ProgrammableWeb. Public APIs are only the tip of the iceberg, however. There are many APIs that are used to fulfill business contracts but aren't published. Ask your customers or suppliers about them.

The majority of APIs require registration as the API provider has a legitimate interest in knowing who's consuming their APIs and protecting themselves from malicious usage.

For BASF APIs, you need to register for the developer portal by following the instructions in the Get Started guide. Some APIs require additional approval measures, as described in the documentation of the respective API product.

For APIs from other providers, follow the instructions that you find on their developer portal.

What are OpenAPI and Swagger?

When learning about APIs, you often read or hear about OpenAPI and Swagger.

OpenAPI is a machine-readable description format for APIs. You can think of it as a way to have a handbook for an API that a computer program can understand, too. On the API provider side, OpenAPI helps during the development to keep all implementation and documentation assets synchronized. As an API consumer, you can take the OpenAPI description from the API provider (if they offer one). You can then use it for testing the APIs with custom tools or for generating code.

Swagger is the historical name of the same specification, and it is often used interchangeably. However, it's better to use the newer, more appropriate name OpenAPI.

Today, SmartBear Software offers a set of tools – both open-source and commercial – for working with OpenAPI descriptions under the Swagger brand.

What are the important API styles that I should know?

APIs have a variety of use cases, such as accessing data or triggering functionality. The API Design describes the structure and semantics of the API, and there are multiple styles, or paradigms, that APIs may follow.

CRUD/RESTful

The most common paradigm is the CRUD or RESTful style. Here, the mental model of the APIs is a set of related resources with which a consumer can interact.

CRUD stands for Create-Read-Update-Delete, which are the typical operations that can be performed on data. Resources are domain concepts. For example, the API for a project management system may have resources such as projects, tasks, and people. Typical things an API consumer could do are: create a project, read all the tasks assigned to a person, update the task to indicate progress, or delete a person that no longer works on the project.

Every resource has its unique URL. For example, a project could be identified with https://api.example.com/projects/1. The CRUD operations loosely map to HTTP methods; GET for reading, POST for creating, PUT for updating, and DELETE for deleting.

It’s very straightforward to get started with this kind of API, even for beginners, especially when the use case of the API consumer involves just reading data. Making a GET request to a resource URL is essentially the same as opening a web page in a browser, with the only difference that the data the server returns is in a different format.

REST stands for Representational State Transfer and describes several concepts first outlined in the doctoral dissertation of Roy Fielding. These concepts go further than the above description. They, for example, include the idea of Hypermedia, a mechanism for “self-discovery”, which is way beyond the scope of this introduction. Most CRUD APIs are called REST APIs or RESTful APIs, but it’s useful to realize that this is a colloquial usage of the term as they typically do not implement Hypermedia.

Query-based (GraphQL)

A paradigm that has gained much traction with the introduction of the GraphQL protocol is query-based APIs. The idea behind query-based APIs is that the API consumer formulates a question, or query, to describe the information they need.

In CRUD/REST APIs, you always get a full representation of the resource, just as a web browser always shows you a complete page. With query-based APIs, you can specify which of the fields of a resource type and related resources you need. In our project management scenario explained above, for example, you could ask the API to list all tasks in all projects. You can then specify only to include the title of each task and no other information, such as who's working on them.

If you have some familiarity with relational databases (MySQL, Access, etc.), you could think of GraphQL or other query formats as the API analogy to SQL (the Structured Query Language that is commonly used to interact with them).

RPC

RPC (Remote Procedure Call) is a style in which describes the API as a set of commands that the consumer can make. RPC APIs used to be very common with XML-RPC, JSON-RPC, and SOAP as traditional protocols. In contrast, newer APIs optimized for performance often use gRPC, a binary protocol.

Many RPC APIs expose classes and methods from object-oriented programming over a network. They are rarely used for public APIs and more prevalent within the enterprise, where for historical reasons, especially SOAP is quite popular.

How can I consume APIs, even without building an application?

If you are not a developer or the application in which you want to consume an API does not exist yet, it is useful to have a way of making API requests without writing any code. Luckily there is more than one way to do so.

Developer Portal

Many developer portals, including the BASF portal, provide interactive API documentation. That means you can go to the documentation for a specific API Product, add your parameters into a form, send the API request, and see the response directly on the page.

Browser

As mentioned earlier in this introduction, APIs are similar to the requests a browser makes. Therefore, you can view the response for an API URL directly in your browser. That approach works, however, only when the API requires no custom HTTP headers – such as a specific method of API authentication – or an HTTP method other than GET.

cURL

This command-line utility is a staple of macOS and nearly all Linux distributions and available as a free download for Windows and other systems. You can use it to send any kind of HTTP request with every feature of the HTTP protocol, such as custom headers. While this tool is very flexible, we recommend it for those who have some experience with the HTTP protocol. On the other hand, many developer portals or other tools offer cURL samples that you can simply copy and paste to a command prompt.

Postman

This desktop application allows you to build HTTP requests visually, which makes it more beginner-friendly than cURL. You can even import OpenAPI files and organize stored requests in collections. We have a full Postman tutorial available that helps you get started.

Excel and Google Sheets

Many spreadsheet applications, both desktop and web-based, can include data from APIs directly into a spreadsheet. For the Windows version of Excel, we have a full tutorial available that helps you get started.

Python

It is a programming language, of course, but one with wide usage and beginner friendliness. On top of Python, Jupyter helps you write and document code that uses APIs without having to set up a full application yourself. We have a full Python tutorial available that helps you get started.

Where do I get help?

The BASF Group has a central email box to answer questions and collect feedback about the APIs. You can write to developer@basf.com or use the contact form on the portal.