API

Interface de programmation d'application
Un article de Wikipédia, l'encyclopédie libre
«API» redirige ici. Pour d'autres utilisations, voir API (homonymie).
Pour la MediaWiki (le logiciel utilisé par Wikipedia) API, voir MW: API
Dans la programmation informatique, une interface de programmation d'application (API) est un ensemble de routines, de protocoles et d'outils pour la construction de logiciels et d'applications.

Une API exprime un composant logiciel en termes de ses opérations, entrées, sorties, et les types sous-jacentes, la définition des fonctionnalités qui sont indépendants de leurs implémentations respectives, ce qui permet des définitions et des implémentations varient sans compromettre l'interface. Une bonne API facilite l'élaboration d'un programme en fournissant tous les blocs de construction, qui sont ensuite mis en place par le programmeur.

Une API peut être pour un système basé sur le Web, système d'exploitation, ou d'un système de base de données, et il fournit des installations pour développer des applications pour ce système en utilisant un langage de programmation donné. A titre d'exemple, un programmateur qui développe des applications pour Android peut utiliser une API Android pour interagir avec le matériel, comme la caméra frontale d'un dispositif basé sur Android.

En plus d'accéder à des bases de données ou de matériel informatique comme les disques durs ou cartes vidéo, une API peut faciliter le travail de la programmation GUI composants. Par exemple, une API peut faciliter l'intégration de nouvelles fonctionnalités dans des applications existantes (un soi-disant "plug-in API"). Une API peut également aider autrement applications distinctes avec le partage de données, qui peuvent aider à intégrer et améliorer les fonctionnalités des applications.

API viennent souvent sous la forme d'une bibliothèque qui comprend des spécifications pour les routines, les structures de données, des classes d'objets et des variables. Dans d'autres cas, notamment SOAP et REST des services, une API est simplement une spécification des appels distants exposés aux consommateurs de l'API. [1]

Une spécification d'API peut prendre de nombreuses formes, y compris une norme internationale, tels que POSIX, la documentation du fournisseur, comme le Microsoft Windows API ou les bibliothèques d'un langage de programmation, par exemple, la Standard Template Library en C ++ ou les API Java.

Une API diffère d'une interface binaire d'application (ABI) en ce qu'une API est basée-code source tandis qu'un ABI est une interface binaire. Par exemple POSIX est une API, tandis que le Linux Standard Base fournit une ABI. [2] [3]

Contenu [Masquer]
1 utilisations
1.1 API dans les langages procéduraux
1.2 API dans les langages orientés objet
1.3 bibliothèques et les cadres API
1,4 API et protocoles
1.4.1 Objet API et protocoles d'échange
1.4.2 Objet API et protocoles d'accès distant
1,5 partage et la réutilisation de l'API par machine virtuelle
2 API Web
2.1 utiliser le Web pour partager du contenu
3 implémentations
4 la conception de l'API
5 politiques de sortie
5.1 implications API publiques
5.2 API dévalorisation
6 documentation de l'API
6.1 documentation de référence de l'API
7 API et les droits d'auteur
8 exemples de l'API
9 liaisons de langage et des générateurs d'interface
10 Voir aussi
11 Remarques
12 Références
13 Davantage de lecture
Usages [edit]
API dans les langages procéduraux [modifier]
Dans la plupart des langages procéduraux, une API spécifie un ensemble de fonctions ou des routines qui accomplit une tâche spécifique ou, sont autorisés à interagir avec un composant spécifique du logiciel. Cette spécification est présenté dans un format lisible par l'homme dans les livres en papier ou en format électronique comme eBooks ou des pages de manuel. Par exemple, l'API de calcul sur Unix systèmes est une spécification sur la façon d'utiliser les fonctions mathématiques inclus dans la bibliothèque de mathématiques. Parmi ces fonctions, il est une fonction nommée sqrt (), qui peut être utilisé pour calculer la racine carrée d'un nombre donné.

La commande Unix man 3 sqrt présente la signature de la fonction sqrt sous la forme:

SYNOPSIS
#include
double sqrt ( double X );
float sqrtf ( float X );
DESCRIPTION
sqrt computes the positive square root of the argument . ...
RETURNS
On success , the square root is returned . If X is real and positive ...
Cette description signifie que sqrt () renvoie la racine carrée d'un nombre à virgule flottante positif (simple ou à double précision), comme un autre nombre à virgule flottante. La page de manuel indique également que le programme appelant doit inclure le math.h fichier d'en-tête pour être en mesure de référencer les fonctions présentes dans la bibliothèque mathématique.

Ainsi l'API dans ce cas peut être interprété comme la collecte des fichiers à inclure utilisés par un programme, écrit en langage C, faire référence à cette fonction de bibliothèque, et sa description lisible par un humain fourni par les pages de manuel.

De même, d'autres langues ont des bibliothèques de procédure; par exemple, Perl a des API dédiées pour la même tâche mathématique avec une documentation intégrée disponible, qui est accessible en utilisant le perldoc utilitaire:

$ Perldoc -f sqrt
sqrt EXPR
sqrt #return la racine carrée de EXPR. Si EXPR est omis, retourne
#square racine de $ _. Ne fonctionne que sur des opérandes non négatifs, sauf si
# vous avez chargé le module Math :: Complex standard.
API dans les langages orientés objet [modifier]
Dans sa forme la plus simple, une API de l'objet est une description de la façon dont les objets fonctionnent dans un langage orienté objet-donnée - habituellement il est exprimé comme un ensemble de cours avec une liste associée des méthodes de classe.

Par exemple, dans le langage Java, si la classe Scanner doit être utilisé (une classe qui lit l'entrée de l'utilisateur dans les programmes à base de texte), il est nécessaire d'importer la java.util.Scanner bibliothèque, donc des objets de type Scanner peut être utilisé en invoquant certaines des méthodes de la classe:

importation java.util.Scanner;

publique classe test
{publique statique vide principale (Cordes [] args)
{Système. à. println ("Entrez votre


nom est "+ nom +". ");
inputScanner. close

();}}
Dans l'exemple ci-dessus, les méthodes nextLine () et close () font partie de l'API pour le Scanner classe, et donc sont décrits dans la documentation de cette API, par exemple:

public String nextLine ()

Avances ce scanner passé la ligne courante et retourne l'entrée sautée ...

Retours:

la ligne qui a été sautée

Lance:

NoSuchElementException - si aucune ligne trouvé

IllegalStateException - si ce scanner est fermé

Plus généralement, en orienté objet langues, une API comprend généralement une description d'un ensemble de classe définitions, avec un ensemble de comportements associés à ces classes. Ce concept abstrait est associé à la fonctionnalité réelle exposée, ou mis à disposition, par les classes qui sont mises en œuvre en termes de méthodes de classe (ou plus généralement par l'ensemble de ses composantes publiques donc toutes les méthodes publiques, mais aussi éventuellement y compris une entité interne rendue publique comme : champs, des constantes, des objets imbriqués, énumérations, etc.).

L'API dans ce cas peut être conçue comme l'ensemble de toutes les méthodes exposées publiquement par les classes (généralement appelé la classe d'interface). Cela signifie que l'API prescrit les méthodes qui interagit avec une / gère les objets provenant des définitions de classes.

Plus généralement, on peut voir l'API que la collecte de tous les types d'objets, on peut tirer des définitions de classe, et leurs comportements associés possibles. Encore une fois: l'utilisation est médiée par les méthodes publiques, mais dans cette interprétation, les méthodes sont considérés comme un détail technique de la façon dont le comportement est mis en œuvre.

Par exemple: une classe représentant une pile peut simplement exposer publiquement deux méthodes push () (pour ajouter un nouvel élément à la pile) et pop () (pour extraire le dernier élément, idéalement placé sur le dessus de la pile).

Dans ce cas, l'API peut être interprété comme le deux méthodes pop () et push (), ou, plus généralement, que l'idée que l'on peut utiliser un objet de type de pile qui implémente le comportement d'une pile: un tas d'exposer son sommet pour ajouter / supprimer des éléments. La seconde interprétation semble plus approprié dans l'esprit de l'orientation objet.

Ce concept peut être effectuée au point où une interface de classe dans une API n'a pas de méthode du tout, mais seulement les comportements qui lui est associé. Par exemple, le Java et Lisp API linguistiques comprennent l'interface de nom Serializable, qui est une interface de marqueur qui nécessite la mise en œuvre de chaque classe, il se comporter dans un feuilleton mode. Cela ne nécessite pas la mise en œuvre d'une méthode publique, mais exige plutôt que toute classe qui implémente cette interface doit être basée sur une représentation qui peut être sauvé (sérialisé) à tout moment. [Une]

De même, le comportement d'un objet dans une concurrente (multi-filetée environnement) est pas nécessairement déterminée par des méthodes spécifiques, appartenant à l'interface mise en œuvre, mais appartient toujours à l'API pour cette catégorie d'objets, et doit être décrit dans la documentation. [ 4]

En ce sens, dans les langages orientés objet, l'API définit un ensemble de comportements d'objets, peut-être médiés par un ensemble de méthodes de classe.

Dans ces langues, l'API est toujours distribué comme une bibliothèque. Par exemple, les bibliothèques du langage Java comprennent un ensemble d'API qui sont fournis sous la forme de la JDK utilisé par les développeurs de créer de nouveaux programmes de Java. Le JDK inclut la documentation de l'API dans JavaDoc notation.

La qualité de la documentation associée à une API est souvent un facteur déterminant de son succès en termes de facilité d'utilisation.

Bibliothèques d'API et de cadres [modifier]
Une API est généralement liée à une bibliothèque de logiciels: l'API décrit et prescrit le comportement attendu tandis que la bibliothèque est une mise en œuvre effective de cet ensemble de règles. Une seule API peut avoir la mise en œuvre multiple (ou pas, être abstraite) sous la forme de différentes bibliothèques qui partagent la même interface de programmation.

Une API peut également être liée à un cadre logiciel: un cadre peut être fondée sur plusieurs bibliothèques d'exécution plusieurs API, mais contrairement à l'utilisation normale d'une API, l'accès au comportement intégré dans le cadre est médiée par l'extension de son contenu avec de nouvelles classes branché sur le cadre lui-même. En outre, le flux global du programme de contrôle peut être hors du contrôle de l'appelant, et dans les mains du cadre par l'inversion de contrôle ou un mécanisme similaire. [5] [6]

API et protocoles [modifier]
Une API peut également être une implémentation d'un protocole.

Lorsqu'une API met en oeuvre un protocole, il peut être basé sur proxy procédés pour invocations éloignées qui dépendent en dessous sur le protocole de communication. Le rôle de l'API peut être exactement à cacher le détail du protocole de transport. Par exemple: RMI est une API qui implémente l'JRMP protocole ou l'IIOP comme RMI-IIOP.

Protocoles sont généralement partagées entre les différentes technologies (système basé sur les langages de programmation informatique donnés dans un système d'exploitation donné) et, généralement, les différentes technologies permettront d'échanger des informations, agissant comme un niveau abstraction / médiation entre les deux environnements différents. Protocole peut donc être considéré comme distants API, locaux API place sont habituellement spécifiques à une technologie donnée: d'où une API pour une langue donnée ne peut pas être utilisé dans d'autres langues, à moins que les appels de fonction sont enveloppés avec des bibliothèques d'adaptation spécifiques.

Pour permettre l'échange d'informations entre les systèmes qui utilisent des technologies différentes, quand une API met en œuvre un protocole, il peut prescrire un langage neutre format de message: par exemple SOAP utilise XML comme un conteneur général pour les messages à échanger, de même API REST peut utiliser à la fois XML et JSON.

Objet API de change et des protocoles [modifier]
Une API de l'objet peut prescrire un format d'échange d'objet spécifique qu'un programme peut utiliser localement dans une application, tout un protocole d'échange d'objet peut définir une façon de transférer le même genre d'informations dans un message envoyé à un système distant.

Quand un message est échangé via un protocole entre les deux plates-formes différentes en utilisant des objets sur les deux côtés, l'objet dans un langage de programmation peut être transformé (mobilisées et unmarshalled [7]) dans un objet dans une langue à distance et différent: ainsi, par exemple, un programme écrit en Java invoque un service via SOAP ou IIOP écrit en C # deux programmes utilisent des API pour l'invocation à distance (chacun localement à la machine sur laquelle ils travaillent) à (distance) d'échanger des informations que les deux convertissent à partir de / à un objet dans la mémoire locale .

Au lieu de cela quand un objet similaire sont échangées via une API locale à une seule machine l'objet est effectivement échangée (ou une référence à elle) dans la mémoire: par exemple via la mémoire allouée par un processus unique, ou entre plusieurs processus en utilisant la mémoire partagée, un serveur d'application , ou d'autres technologies de partage comme espaces de tuple.

Objet API d'accès distant et les protocoles [modifier]
Une API objet de communication à distance est basé sur un protocole de communication à distance, tels que CORBA, qui permet à la méthode objet distant invocation. Un appel de méthode, exécutée localement sur ​​un objet proxy, appelle la méthode correspondante sur l'objet à distance, en utilisant le protocole de communication à distance, et acquiert le résultat doit être utilisé localement comme valeur de retour. [8]

Lorsque l'accès distant est en place, une modification sur l'objet proxy correspond à une modification de l'objet distant. Lorsque seul un transfert de l'objet a lieu, la modification à la copie locale de l'objet ne se reflète pas sur l'objet d'origine, sauf si l'objet est renvoyé à l'expéditeur.

Le partage et la réutilisation de l'API via la machine virtuelle [modifier]
Certaines langues, comme ceux en cours d'exécution dans une machine virtuelle (par exemple .NET langues CLI conformes à l'heure Langue Run commun (CLR), et JVM langues conformes à la machine virtuelle Java) peuvent partager une API. Dans ce cas, une machine virtuelle permet l'interopérabilité de langue, en faisant abstraction d'un langage de programmation en utilisant un intermédiaire byte code et de ses liens avec le langage. Dans ces langues, le compilateur effectue compilation à la volée ou de la compilation de l'avant-des-temps de transformer le code source, peut-être écrit en plusieurs langues, dans sa représentation de byte code indépendant de la langue.

Par exemple, à travers la représentation de byte code, un programme écrit en Groovy ou Scala langue peut utiliser toute classe Java standard et donc toute API Java. Ceci est possible grâce au fait Groovy et Scala ont un modèle d'objet qui est un ensemble de celle du langage Java de super; Ainsi, toute API exposées par un objet Java est accessible via Groovy ou Scala par une invocation d'objet équivalent traduit en code octet.

De l'autre côté, Groovy et Scala introduisent de première classe des entités qui ne sont pas présents en Java, comme des fermetures. Ces entités ne peuvent pas être représentés nativement en langage Java (Java 8 introduit le concept de l'expression lambda); Ainsi, pour permettre le fonctionnement inter, une fermeture est encapsulé dans une norme objet Java. Dans ce cas, l'invocation de fermeture est médiée par un nommé méthode call (), qui est toujours présente dans un objet de fermeture comme on le voit par Java, et Java la fermeture ne représente pas une première classe entité.

API Web [modifier]
Article détaillé: API Web
API Web sont les interfaces définies par lequel se produisent les interactions entre une entreprise et les applications qui utilisent ses actifs. Une approche de l'API est une approche architecturale qui tourne autour de fournir des interfaces programmables pour un ensemble de services à différentes applications servant différents types de consommateurs. [9] Lorsqu'il est utilisé dans le contexte de développement web, une API est généralement définie comme un ensemble de Hypertext Transfer Protocole (HTTP) des messages de demande, avec une définition de la structure des messages de réponse, qui est généralement dans un langage de balisage extensible (XML) ou JavaScript Object Notation (JSON) le format. Alors que "API Web" historiquement a été pratiquement synonyme de service Web, la tendance récente (dite Web 2.0) a été déplacer loin de protocole Simple Object Access (SOAP) services Web et l'architecture orientée services (SOA) en direction plus directe transfert de représentation de l'Etat (Rest) de style ressources Web et axées sur les ressources de l'architecture (ROA). [10] Une partie de cette tendance est liée à la Web sémantique mouvement vers Resource Description Framework (RDF), un concept de promouvoir sur le web ingénierie ontologique technologies . API Web permettent la combinaison de plusieurs API dans de nouvelles applications appelées mashups. [11]

L'utilisation du Web pour partager du contenu [modifier]
La pratique de l'API d'édition a permis aux communautés Web pour créer une architecture ouverte pour le partage de contenu et de données entre les communautés et les applications. De cette façon, le contenu qui est créé dans un endroit peut être affiché et mis à jour dynamiquement à plusieurs endroits sur le web:

Les photos peuvent être partagées sur des sites comme Flickr et Photobucket pour réseaux sociaux sites comme Facebook et MySpace.
Le contenu peut être incorporé, par exemple, intégrer une présentation de SlideShare sur un LinkedIn profil.
Le contenu peut être affiché dynamiquement. Partage de commentaires en direct effectués sur Twitter avec un compte Facebook, par exemple, est activé par leurs API.
Le contenu vidéo peut être intégré sur des sites desservis par un autre hôte.
Informations sur l'utilisateur peut être partagée des communautés Web à des applications à l'extérieur, offrant de nouvelles fonctionnalités à la communauté web qui partage ses données de l'utilisateur via une API ouverte. Un des meilleurs exemples est la plate-forme d'applications Facebook. Un autre est le Open Social plate-forme. [12]
Si le contenu est une représentation directe du monde physique (par exemple, la température à un endroit géospatiales sur terre), puis une API peut être considéré comme une "interface de programmation de l'environnement" (PEV). EPI se caractérisent par leur capacité à fournir un moyen pour les événements universellement séquençage suffisantes pour utiliser les données du monde réel pour la prise de décision.
Implémentations [modifier]
Le POSIX norme définit une API qui permet d'écrire un large éventail de fonctions informatiques courantes de façon à ce qu'ils puissent fonctionner sur de nombreux systèmes différents (Mac OS X, et divers Berkeley Software Distributions (BSD) de mettre en œuvre cette interface). Cependant, en utilisant ce qui nécessite re-compiler pour chaque plate-forme. Une API compatible, d'autre part, permet compilé code objet pour fonctionner sans aucune modification au système qui met en œuvre cette API. Ceci est bénéfique pour les deux fournisseurs de logiciels (où ils peuvent distribuer des logiciels existants sur les nouveaux systèmes sans produire et → distribution de mises à jour) et les utilisateurs (où ils peuvent installer des logiciels plus anciens sur leurs nouveaux systèmes sans avoir à acheter les mises à niveau), bien que cela nécessite généralement que les diverses bibliothèques de logiciels mettre en œuvre les API nécessaires ainsi.

Microsoft a montré un engagement fort pour une API compatible en arrière, en particulier au sein de leur API Windows (Win32) bibliothèque, de telle sorte que les anciennes applications peuvent fonctionner sur les versions plus récentes de Windows en utilisant un cadre exécutable spécifique appelé "mode de compatibilité". [13]

Parmi Unix-like systèmes d'exploitation, il existe de nombreux systèmes d'exploitation connexes, mais incompatibles fonctionnant sur ​​une plate-forme matérielle commune (notamment Intel 80386 des systèmes compatibles avec le standard). Il ya eu plusieurs tentatives de standardisation de l'API tels que les éditeurs de logiciels peuvent distribuer une application binaire pour tous ces systèmes; Cependant, à ce jour, aucune de ces a rencontré beaucoup de succès. Le Linux Standard Base tente de le faire pour le Linux plate-forme, alors que beaucoup de BSD Unix, tels que FreeBSD, NetBSD et OpenBSD, mettre en œuvre différents niveaux de compatibilité de l'API pour la compatibilité descendante (permettant des programmes écrits pour les anciennes versions à exécuter sur nouvelles distributions du système) et la compatibilité multi-plateforme (permettant l'exécution de code étranger sans avoir à recompiler).

La conception de l'API [edit]
Plusieurs principes sont couramment utilisés pour régir le processus de conception d'API. Parnas proposé le concept de dissimulation d'information en 1972. Le principe de masquage d'information est que l'on peut diviser les logiciels en modules, dont chacun a une interface spécifiée. Les interfaces cachent les détails des modules de mise en œuvre afin que les utilisateurs de modules ne doivent pas comprendre les complexités à l'intérieur des modules. Ces interfaces sont des API, et en conséquence, les API devraient exposer uniquement les modules de détails que les clients doivent savoir pour utiliser des modules de manière efficace. L'architecture logicielle est dédié à la création et le maintien de structures, qui logiciels de haut niveau inclut généralement des modules. API reflètent interfaces entre modules. Ainsi, une architecture de système est inextricablement lié au API qui expriment cette architecture. Cependant, de nombreuses décisions impliqués dans la création architecturale API ne sont pas, comme les conventions de nommage et de nombreux détails sur la façon dont les interfaces sont structurés.

Ces détails de la façon dont les interfaces sont structurés, ainsi que l'architecture du logiciel, ont des impacts importants sur la qualité du logiciel. Par exemple, Cataldo et al. constaté que bugginess est corrélée avec dépendances logiques et de données dans le logiciel. [14] Cela implique que, pour réduire les taux de bugs, les développeurs de logiciels devraient examiner attentivement les dépendances de l'API.

La loi de Conway déclare que la structure d'un système reflète inévitablement la structure de l'organisation qui l'a créé. Cela suggère que, pour comprendre comment les API sont conçus dans le monde réel, il faut aussi comprendre les structures des organisations de génie logiciel. De même, un groupe API doit se structurer en fonction de ce besoin de l'API. Dans une étude de 775 ingénieurs logiciels Microsoft, Begel et al. ont constaté que, en plus de la coordination en ce qui concerne la conception de l'API, les ingénieurs logiciels encore plus couramment coordonnent concernant les horaires et les caractéristiques. [15] Cela renforce le point de vue que les organisations de logiciels collaborent intensivement et que la structure organisationnelle est important.

Plusieurs auteurs ont créé des recommandations sur la façon de concevoir les API, tels que Joshua Bloch [16] et Michi Henning. [17] Cependant, puisque l'un des principes de la conception de l'API est que l'API devrait être compatible avec d'autres API déjà en usage dans la système, les détails de la conception de l'API sont un peu la langue et à dépendant du système.

Les politiques de sortie [modifier]
Les principales politiques pour libérer une API sont:

Protection des informations sur les API du grand public. Par exemple, Sony utilisé pour officialiser sa PlayStation 2 API uniquement disponible pour les développeurs PlayStation licence. Cela a permis à Sony de contrôler qui a écrit les jeux PlayStation 2. Cela donne des privilèges de contrôle des sociétés de qualité et peut leur fournir des sources de revenus de licence potentiels.
Faire API disponible gratuitement. Par exemple, Microsoft rend le Microsoft Windows publique de l'API, et d'Apple publie son API Carbon et Cocoa, afin que le logiciel peut être écrit pour leurs plates-formes.
Un mélange de ces deux comportements peuvent être utilisés aussi bien.

Implications de l'API publique [modifier]
Une API peut être développé pour un groupe restreint d'utilisateurs, ou il peut être rendu public.

Un facteur important lors d'une API devient publique est sa stabilité d'interface. Changements par un développeur à une partie de celui-ci, par exemple en ajoutant de nouveaux paramètres à une fonction d'appel pourrait briser la compatibilité avec les clients qui dépendent de cette API.

Lorsque des parties d'une API présenté publiquement sont sujets à changement et donc pas stable, ces parties d'une API particulière devrait être explicitement documentées comme instable. Par exemple, dans le Google Guava bibliothèque les parties qui sont considérées comme instable, et qui pourrait changer dans un futur proche, sont marqués avec l'annotation JavaBeta. [18]

API dévalorisation [modifier]
Une API publique peut parfois déclarer parties de lui-même comme obsolète. Cela signifie généralement que la partie d'un API devrait être considéré candidated pour être supprimé ou modifié d'une manière incompatible arrière.

Lors de l'adoption d'une API publique tiers, les développeurs doivent tenir compte de la politique de dépréciation utilisée par le producteur de cette API; si un développeur rend public une solution basée sur une API qui devient obsolète, il / elle pourrait être incapable de garantir le service fourni.

API documentation [modifier]

Cette section ne cite pas de sources. S'il vous plaît aider à améliorer cet article en ajoutant des citations aux sources fiables. La matière d'Unsourced peut être défiée et enlevée. (Avril 2015)
La documentation de niveau professionnel [19] pour une API devrait s'efforcer d'inclure les éléments suivants:

Documentation de référence
Une description des fonctions et des objets dans l'API (voir le paragraphe documentation de référence de l'API)
Vue d'ensemble et concepts
Une description narrative des différentes parties de l'API et comment ils interagissent. Les principaux cadres de l'API, comme son interface graphique, réseau, et des cadres du système de fichiers doivent avoir leur propre section distincte.
Tutoriels / classes de formation
Étape par étape les instructions qui montrent aux développeurs comment accomplir une tâche particulière. Le texte devrait inclure le code que les développeurs peuvent copier dans leurs propres applications. Par exemple, une classe de formation pour une API cryptographique inclurait code qui montre aux développeurs comment utiliser l'API pour crypter un fichier.
Installation Mise en route documentation / / dépannage
Un ou plusieurs documents qui montrent aux développeurs comment faire ce qui suit:
Procurez-vous le kit de développement logiciel (SDK) pour l'API
Installez le SDK sur une machine de développement
Obtenir les clés, les comptes, et ainsi de suite qui permettent l'accès
Déployer ou fournir des bibliothèques clientes
Résoudre les problèmes avec l'aide du SDK
La documentation des outils SDK
Documents qui décrivent comment installer et utiliser build, compiler et déployer des outils
Informations sur la licence
Documents qui décrivent la licence de l'API
La documentation de référence de l'API [edit]
La documentation de référence pour une API est une partie intrinsèque de toute API, et sans elle, l'API est inutilisable. Chaque aspect de l'API, peu importe comment trivial, doit être clairement indiqué.

Quand une API documente une bibliothèque de fonctions dans un langage procédural, il devrait inclure:

une description de toutes les structures de données elle dépend
une description de toutes les fonctions des signatures, y compris:
les noms de fonctions
fonction des paramètres de noms (quand il applique) et types
le type de retour pour les fonctions
pour chaque paramètre si le paramètre est éventuellement soumis à une modification à l'intérieur de la fonction
une description de la manipulation de toute condition d'erreur
pré et post-conditions ou invariants
plus généralement comment l'Etat a changé après l'exécution de la fonction
possibles effets secondaires
toute accessibilité ou la visibilité contrainte.
Une API de l'objet devrait documenter:

la relation de tout type à d'autres types: l'héritage (super-types, sous-types, mis en œuvre des interfaces ou traits), structures composites, entités déléguant ou toute mixte en jeu de fonctionnalité
le publique partie d'un objet issu d'une définition de classe, donc:
ses publiques constantes
le nom et le type des variables membres (champs ou propriétés) qui sont directement accessibles pour tout objet
la signature des méthodes de classe, y compris des informations similaires à celles pour les fonctions dans les langues de procédure, y compris éventuellement une liste de getter et setter méthodes utilisées pour accéder ou modifier les informations encapsulé
des opérateurs spécifiques à chaque classe, dans le cas de la langue prend en charge la surcharge d'opérateur
indication si les champs ou les méthodes ont une statique nature
toute contrainte qui applique aux objets on peut créer
structures imbriquées, comme les classes internes ou énumérations.
Une API dans une langue utilisant la gestion des exceptions devraient signaler toute sorte d'exception éventuellement jetés et la condition spécifique qui peut les amener à se produire.

Une API qui peut être utilisé dans une concurrente environnement devrait inclure des indications sur la façon dont son comportement change en raison de possible l'accès simultané à elle: la facilité d'utilisation générale dans un contexte concurrente et possibles conditions de course. [4]

Une API avec des pièces instables devrait documenter comme instable.

Une API avec obsolètes pièces devrait les documenter comme obsolète.

Une API qui met en oeuvre un protocole de communication doit indiquer son comportement général, et devraient détailler:

Comment mettre en place une session de communication sur la base de ce protocole, et les conditions préalables pour configurer correctement une session de communication
Si la communication est avec ou sans état
En cas de sessions stateful: comment gérer l'état
La notation pour le genre de messages du protocole peut transporter
Comment le protocole gère les erreurs de communication
Si, en cas d'erreurs de communication, le protocole peut présenter de nouveau un message
Les niveaux de sécurité pris en charge, et de la façon de sécuriser la communication
Authentification nécessaire de mettre en place une session
Si la communication ne peut être associé à un traitement transactionnel, et par conséquent, la façon de traiter des transactions
Si la communication peut être intégré dans une étendue la conversation, et par conséquent comment gérer la conversation
Une API graphique devrait documenter:

Les éléments graphiques qu'il peut gérer
Comment rendre les éléments graphiques
Comment exposer éléments sur la toile graphique, et la façon de les composer
Comment interagir avec les éléments graphiques
La façon de traiter une entrée d'utilisateur, par exemple,
Comment ajouter rappel à des événements spécifiques de l'utilisateur
Comment lire les informations de champs de saisie
Une API qui interagit avec un dispositif doit documenter comment:

Accéder à l'appareil pour extraire des données de celle-ci
Modifier l'état de l'appareil, lorsque cela est possible
Détecter les conditions d'erreur dans l'appareil.
Une API devrait toujours indiquer, le cas échéant:

Langue numéro de version
Bibliothèque et autres dépendances de ressources
Versions de protocole est compatible avec ou qu'elle mette en œuvre
Système d'exploitation ou la version de la plate-forme il supporte
Une API qui peut être utilisé dans de multiples langues via une certaine forme de langue inter-opération doit documenter toutes les restrictions à son utilisation par d'autres langues que le natif langue.

Documentation de l'API peut être enrichi avec des métadonnées informations: comme annotation Java, ou les métadonnées de CLI. Ces métadonnées peut être utilisé par le compilateur, les outils, et par le run-time environnement à mettre en œuvre des comportements personnalisés ou manipulation personnalisé.