This guide lists all terms related to APIs and to the Orange Developer ecosystem.
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
Application Programming Interface. Piece of software. An application can use this interface to interact with another application that provides a resource (such as datasets).
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.
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
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.
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.
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.
Unique developer application’s identifier in our exposition channel’s information system.
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>).
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.
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)
See API Calls.
Unique ID provided by our API Management solution to identify your application.
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).
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.
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.
HTTP URL / @IP address where the backend receives the HTTP REST request.
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.
Interface Contract. It describes the connection between the API management gateway and the API provider backend (quota, ressource set, verbs, headers, connexion, authentication mode).
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.
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
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.
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.
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.
A useful GUI platform to perform API calls and get answers in REST/JSON format.
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
APIs used internally to facilitate the integration of different applications and systems within a company.
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.
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 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)”
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.
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.
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.
User To Machine. Type of identification requiring an end-user authentication. See OAuth2 3 legged / Oauth2 3-legs
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 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.