.wpb_animate_when_almost_visible { opacity: 1; }

All about APIs – Glossary

Published: April 18, 2024

This guide lists all terms related to APIs and to the Orange Developer ecosystem.

Access token

An access token allows a client application to access data managed by a resource server. This token is generated with the client_id & client_secret app’s credentials, made available on the Orange Developer portal via an OAuth 2.0 authorization server and sent by the client application, in the request (header part) to the resource server. This token is mandatory for APIs calls to access protected resources. For more information on how to generate and use this access token, refer to First steps – Orange Developer

API

Application Programming Interface. Piece of software. An application can use this interface to interact with another application that provides a resource (such as datasets).

API Calls

We may talk about “using an API” or “sending calls or requests using an API” interchangeably. This means that an application consumes the resources of an API. To know which requests an application can send to an API, the technical documentation (e.g. Getting started, Swagger-based API Reference) provides examples of requests/responses.

API Factory

The API Factory encompasses marketing + training + IT + service platforms + networks. It has a double mission:

  • promote API culture inside the Group and define guidelines
  • operate and market APIs to developers, ideally in a self-service mode

API Gateway

Core component of an API Management solution that is used to secure the access to API resources. Acts as a single point of access to route and process request & response messages sent/received by client applications to/from backend services exposed through API proxies.

API Provider

Individual, Business Unit and/or project team who distributes an API offer through the Orange Developer channel. From the developer point-of-view, the API Provider is your first contact concerning the API usage.

API Proxy

Provides a technical facade for the backend service to be exposed through the API gateway ; it decouples the backend service implementation of the API that developers consume. It enforces technical policies for request/response flows: security, quota, message validation/filtering/enrichment, logging, routing… Its responsibility is to ease and control (authorize or reject) the exchanges between the API and the outside applications.

Application ID

Unique developer application’s identifier in our exposition channel’s information system.

Authorization header

Used to get an access token. Its value is composed of the keyword “”Basic””, followed by a space and the base64 encoding of the concatenation of the client_id, “”:”” and the client_secret. It is then included in every API call with the Bearer token value to ensure you are allowed to access the API resources (Authorization: Bearer <access_token>)..

Backend

Hardware equipment where stands the service that you are reaching using an API.

Note that you are responsible for hosting your service, as the API Factory does not provide hosting services. Instead, you may find the hosting that fits your software needs within our Group cloud services.

Base path

Required string that uniquely identifies the URI path used by the API Gateway to route incoming messages to the proper API proxy. The BasePath is a URI fragment (for example /cloud/v1) appended to the base URL of the API Gateway (e.g. https://api.orange.com)

Calls

See API Calls.

Client ID

Unique ID provided by our API Management solution to identify your application.

Client secret

Secret code provided to you by Orange Developer for a given app. It is known only to the application and the OAuth 2.0 authorization server. It is used in conjunction with the client ID to request an access token. It may also be used to sign the ID Token (according to OpenID Connect standard).

Code sample

Editorial content of the ‘Code Samples tab’, which is part of the documentation made available by the API Provider on the Orange Developer portal. It may be a code snippet or a Postman collection that can become code.

ebonding

Act of integrating and automating bi-directional data synchronization between unique enterprises and their systems. eBonding also refers to the B2B software interface that automates the data exchange between two business applications, reducing the amount of manual intervention that’s usually required.

End-Point

HTTP URL / @IP address where the backend receives the HTTP REST request.

Getting started

Guide which provides all the information you need to start using the API (step-by-step guide to use the API):

  • Examples of requests and responses
  • a way to replicate these examples using a REST API utility software such as Postman or RESTClient (a Firefox plug-in).

This guide ensures you understand the scope of the API and get up and running as quickly as possible.

IC

Interface Contract. It describes the connection between the API management gateway and the API provider backend (quota, ressource set, verbs, headers, connexion, authentication mode).

JSON

JavaScript Object Notation is a standardized format type for machine-readable information. APIs based on Orange API Design recommendations provide responses or push some structured data in this format.

M2M

Machine To Machine. See eBonding

OAuth 2 legged / Oauth 2-legs

Standard to authorize -or reject- an application’s access to API resources. It does not cover the end-user authentication. All resources need authorization. OAuth v2 framework is used in order to authenticate all calls.

OAuth 2.0 protocol

Protocol for securing application access to protected resources, which are accessed through REST APIs. OAuth 2.0 relies on access tokens presented by client applications when requesting access to protected resources.

OAuth 3 legged / Oauth 3-legs

Adds the end-user authentication and consent to the Oauth 2 legged.

OIDC

OpenID Connect is a simple identity layer on top of the OAuth 2.0 protocol. It enables the end-user’s identity to be verified and their consent to be collected in order to access their personal data

Orange Developer

Online portal where you can explore the Orange API catalog, read API documentation and learn how to use APIs. If you are interested in using an API from the catalog, you must sign-up for a developer account and register some information for the application that will consume the selected API. You then obtain two identifier information (“the credentials”), available in your account, that will authorize your application to send calls to the API. A.k.a. OD. For more information on how to get started, refer to: First steps – Orange Developer.

Overview

Editorial content within the ‘Overview tab’, which is part of the documentation made available by the API Provider in the Orange Developer portal. It describes the value proposition and key benefits of the API. The purpose is to trigger the developer’s interest.

Partners API

Partner APIs are used to facilitate communication and integration of software between a company and its business partners. Such APIs are accessible only on an “invite only” basis to a limited set of third parties or software which communicates across the public Internet.

Postman

A useful GUI platform to perform API calls and get answers in REST/JSON format.

Postman collection

A Postman file produced with the Postman tool. Contains a set of HTTP REST requests. These requests are sent to the provider backend through our API gateway to test part of the offer

Private APIs

APIs used internally to facilitate the integration of different applications and systems within a company.

Public APIs

Public APIs allow companies to publicly expose information and functionalities of one or various systems and applications to third parties that do not necessarily have a business relationship with them.

Refresh token

Special kind of token that can be used to obtain a new access token after it has expired on an OAuth 2.0 authorization server

REST

REST strictly refers to a collection of network architecture principles that outline how resources are defined and addressed. REST describes six constraints that define the basis of REST-style:

  • Client–server: clients are separated from servers by a uniform interface, ensuring separation of concerns. Servers and clients may thus be replaced and developed independently, as long as the interface is not altered.
  • Stateless: each request from any client contains all of the information necessary to service the request, and any state is held in the client.
  • Cacheable: as on the World Wide Web, clients are able to cache responses.
  • Layered system: a client cannot ordinarily tell whether it is connected directly to the end server, or to an intermediary along the way.
  • Code on demand (optional): servers are able to temporarily extend or customize the client’s functionality by transferring logic to it that it can execute.
  • Uniform interface: the uniform interface between client and server simplifies and decouples the architecture, which enables each part to evolve independently. Further a uniform interface has four sub-constraints: identification of resources, manipulation of resources through representations, self-descriptive messages, an hypermedia as the engine of application state (HATEOAS)”

RESTful API

The API Factory has chosen to base the APIs upon some simple RESTful principles rather than SOAP ones: bodies are simpler (JSON), calls are made using four HTTP methods, and URLs are resource-oriented. APIs that adhere to the REST architectural principles rely on standards such as:

  • Uniform Resource identifier (URI). E.g. https://api.orange.com/oauth/v2/authorize
  • Internet media type for the data. Orange recommends JSON but can be any other valid Internet media type (e.g. XML, HTML, audio, images, etc.)
  • HTTP verbs (e.g. GET, POST, PUT, PATCH or DELETE)

REST architecture states that a resource is identified through a URI (Uniform Resource Identifier) with its associated URL, for example: http://mywebsite.com/books is a resource representing the list of all books available from mywebsite.com. Another rule is that RESTful APIs must rely on the native HTTP verbs to carry out actions on the resources of your API: typically, use GET to retrieve a resource, POST to create that resource, PUT to update it, or DELETE to remove it. As a consequence, the actions and resources are strictly separated. For instance, send GET http://mywebsite.com/books to obtain the list of all books or GET http://mywebsite.com/books/87 to obtain the information about the book identified by the number 87.

SDK

Stands for Software Development Kit. Additional layer to the API that hides the API complexity and allows faster integration. A group or series of actions can be performed in a single line. SDKs are hard to build and maintain, and aren’t crucial for launch, but can improve API adoption. If your business model is a public, open API model, having SDKs are a great way to engage with the developer community

Swagger (API Reference)

Defines a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service. The swagger specification file describes the whole set of resources and incoming/outcoming data structure (JSON format) in an offer. The Swagger file is used to create the API Reference of the documentation made available by the API Provider in the Orange Developer portal.  The API Designer tool can automatically generate a swagger.

T&Cs

Editorial content of the ‘Term and Conditions tab’ in the documentation set made available by the API Provider in the Orange Developer portal. These T&Cs come in addition to the generic Orange API T&C. They inform you on conditions or limitations of use regarding the API service and resources. They should cover any business rules related to the API use.

U2M

User To Machine. Type of identification requiring an end-user authentication. See OAuth2 3 legged / Oauth2 3-legs

URI

Stands for Uniform Ressource Identifier. A URI is a string of characters that is used to identify a resource. Such identification enables interaction with representations of the resource over a network, typically the World Wide Web, using specific protocols (e.g. HTTP).

Web Service

Web services are web-based APIs and always need a network connexion for their operation. Not all APIs are web-based. For instance, an Office Suite program uses the PC-operating system APIs.