# API: an agreed way to ask for something

[Concepts explained](README.md)

**API** stands for *Application Programming Interface*. It describes how one piece of software can ask another to do a job. An API can be as small as a group of functions with clear names, inputs, answers, and error rules.

Think of a library desk. You make a request in a form the librarian understands. You do not need to know how every shelf is organized behind the desk.

## A Pliro example

```pliro
# language: en
say length(["red", "blue", "green"])
```

The program asks `length` to count the list's top-level items. Its answer is `3`. The [function reference](../builtins/length.md) is part of the API's documentation: it says what inputs are allowed and what the call returns.

A **built-in** is supplied by the language's standard library rather than defined in your source. In Pliro, localized names still lead to the same canonical operation.

## An API need not use the internet

Drawing, storage, and text functions can all be APIs. A **web API** adds communication with another service over a network. Merely reading about web APIs does not mean Pliro provides arbitrary network access or a built-in named `fetch`.

An API is a contract, not just a function name. Limits, supported hosts, and possible errors matter as much as a successful example.

Try finding the input and return type in the `length` reference. What should happen if you supply a Number instead of a list?

[Parameters](parameters-and-arguments.md) · [Canonical identity](canonical-identity.md)