Introduction to the API
An API (Application Programming Interface) defines a language that software application can use to communicate. The API will sit between two programs (ie. Eclipse and JIRA) and defines a way for them to interact. The Eclipse PPM API can create, retrieve, update, and delete most of the principal Eclipse PPM business entities (Projects, Issues, Risks, Custom Reports, etc.).
Note: This is an introductory overview that explains API basics. However, if you are new to working with APIs, you should do some external research before attempting to integrate the Eclipse PPM API with your application. APIs are extremely complex and can be confusing to new developers.
Caution: Beginning with the Eclipse PPM 2020R3 Release, a new set of JSON-based API endpoints have been made available. The Legacy XML-based endpoints will be deprecated as part of the 2024R2 release expected later this year. When this release is deployed, these endpoints will no longer be functional.
All new integrations should be created using the new endpoints, and any existing integrations should be migrated to them.
There is an easy way to differentiate between the old and new API endpoints. The old endpoints contain "services" in the URL:
None of the new endpoints contain the word "services":
For more information, see What's New with the API.
This introductory article covers the following topics:
The API in Action
The Internet is completely made up of APIs. Every button you press on a web application will make an API call, including the buttons in Eclipse PPM.
Try it:
The Network tab within a web browser's developer tools will display APIs as they run. Follow these steps to see the Eclipse PPM API in action:
-
Log into Eclipse PPM.
- Press Ctrl+Shift+J (Command+Option+J on a Mac or Ctrl+Shift+I on Microsoft Edge) on your keyboard to open up your web browser's DevTools.
-
Click on the Network tab.
-
Click on an entity in Eclipse PPM.
Example: Let's see what happens when we click on a Resource in Eclipse PPM:
We can see that a few Network calls have been made upon clicking this resource. After clicking on the first call (named after the Resource ID), we can see some JSON-formatted information that was retrieved for this resource in the Response tab:
On the webpage itself, we can see that the information from this response has successfully reached its destination:
The Network tab displays all of the API calls the browser makes to get new data for the page. This is essentially how Eclipse PPM works; any interaction you make within the application will use the API to retrieve information.
To put it simply, the API is a messenger between you and a system; it takes your request, tells the system what you want it to do, and then returns a response back to you.
Example: Think of an API as a waiter in a restaurant. After you make a selection from the menu, you tell the waiter (API) what you would like to eat. The waiter then goes over to the kitchen (system) and requests your order. The waiter then delivers your food (response) back to you.
Eclipse PPM API Overview and Requirements
This section describes all the functional and implementation requirements of the Eclipse PPM API. The main purpose of the API is to provide Eclipse PPM users with an additional means of accessing and manipulating data outside of the context of Eclipse PPM.
This section consists of the following topics:
API Scope
Eclipse PPM API is a complementary way of managing client information by leveraging RESTful API services and the Eclipse PPM business-layer codebase. Each API represents a secure point of access to a particular business entity in Eclipse PPM, such as a Project, an Issue, a Risk, a Custom Report, and other relevant entities that these might be linked to. The API can create, retrieve, update, and delete most of the principal Eclipse PPM business entities. This API provides fine-grained retrieval and modification mechanisms, as well as bulk retrieval of data for possible future storage of the information in data warehouses.
Functional and Data Requirements
The following functional and data requirements must be met in order to utilize the Eclipse PPM API.
Functional Requirements
Basic functionality of the API is achieved through the creation of a RESTful HTTP service request (GET, POST, PUT, DELETE) to a specific URL (e.g. https://servername/api/services/projects/). This request can be created in the following way (example in C#):
The request must then be transferred to the server over a secure channel (SSL) where it will be processed, and an HTTP response with an appropriate HTTP status code and JSON or XML content is returned. All the results should be in the context of a given environment (for more details on providing environment information, see Authorization Requirements).
Caution: Beginning with the Eclipse PPM 2020R3 Release, a new set of JSON-based API endpoints have been made available. The Legacy endpoints are still operational, but they will eventually be discontinued at a yet-to-be-determined date. Once this date is confirmed, this article will be updated.
Any new integrations should be created using the new endpoints, and any existing integrations should be migrated to them.
There is an easy way to differentiate between the old and new API endpoints. The old endpoints contain "services" in the URL:
None of the new endpoints contain the word "services":
The following points describe the available operations for each service type:
-
The URL element and the HTTP Method define the operation described in Description.
-
The Query String Parameters are optional flags that provide additional functionality, such as filtering or adding related Eclipse PPM business entity information (e.g. Retrieving projects with linked issues/risks).
-
Response Headers serve as the indicators of a success or a failure of an operation.
Data Requirements
Each service response has two primary parts:
-
The HTTP status
-
The HTTP JSON (or XML) body
The HTTP Status
The status indicates whether the requested operation succeeded or failed, as well as a reason why.
A service response will likely return one of the following statuses:
| Type of Response | Response Code | Description |
|---|---|---|
| Successful responses (200-299) | 200 OK | General indication that the response has returned successfully. This will often occur in the case of a GET when the requested data has been returned. |
| 201 Created | The request has been fulfilled and something new has been created. This should occur in the case of a POST or a PUT when new data generated for Eclipse. | |
| 204 No Content | The request has been fulfilled, but no body needs to be returned. This might appear if metainformation has been updated. | |
| Client (user) errors (400-499) | 400 Bad Request | The request could not be processed due to invalid syntax. For example, you might have sent the wrong JSON body while executing a POST. You should not resend the request without making modifications. |
| 401 Unauthorized | This request requires the user to authenticate itself. When this happens, it usually means that the user did not include the proper credentials in the WWW-Authenticate header field. For more information, see Security Requirements. | |
| 403 Forbidden | The server understands the user's request, but refuses to fulfill it. In this case, not even modifying the authorization will help. | |
| 404 Not Found | The server cannot find anything that matches the request URL. For example, this will occur during a GET for a Resource if the user enters a Resource ID that does not exist in Eclipse. | |
| 409 Conflict | The request could not be completed because a conflict exists between the request and the current state of the entity. This code will only be shown if the user can resolve the conflict and resubmit the request. If this is the case, the response body included with the error should indicate the problem. In the case of a PUT to add a new Resource in Eclipse, for example, a 409 might be returned with a body that indicates "'StatusID' must be greater than '0'." | |
| Server errors (500-599) | 500 Internal Server Error | The server encountered an unexpected problem that prevented it from fulfilling the request. In this case, the server is at fault, not the user who made the request. |
The HTTP Response Body
The response body provides additional information depending on the context of the request. It can either contain the operation result data or some error details if any errors occurred during the operation. Each service provides its own JSON or XML structure based on the Eclipse PPM business entity type that is being used.
Example: Here is the profile page for a Resource in Eclipse PPM:
After running a GET for this Resource, the response body contains the same info that can be found on the Resource's profile page in Eclipse:
Security Requirements
Like any publicly available endpoint, the Eclipse PPM API needs to establish a security model in order to maintain the correctness and safety of its operation. This model has to satisfy two major requirements:
-
Authentication: the act of confirming one's identity to the system.
-
Authorization: the act of giving one access to the system depending on permissions and roles.
Authentication Requirements
Authentication in the Eclipse PPM API is based on a “challenge-response” model over a secure SSL channel. Upon the reception of a request, the API service inspects the request’s authorization header for the presence of a username and a password. If it doesn’t find this information, the API service “challenges” the requester to provide the correct credentials by issuing a specific response containing WWWAuthenticate header. If the requester does not “respond” with valid credentials, then the service issues the response with an "Unauthorized" status code. However, if the “challenge” is satisfied, and the credentials are found, then the service leverages an existing Eclipse PPM authentication system in order to verify them against the credential repository. In case of a successful authentication by the repository, the service proceeds with the next step: authorization. Otherwise, it responds with an "Unauthorized" status code.
In order to correctly respond to the service’s “challenge”, a requester needs to provide proper credentials, as done in the following figure:
Authorization Requirements
The authorization is responsible for identifying one’s scope of influence/operation in the system. Prior to manipulating any data, one’s environment needs to be determined.
The desired environment can be indicated in one of two ways:
-
By adding a “SolutionQ-Environment” header with the value set to the ID of the desired environment. An example of this is shown below:
-
By including the environment name with the username parameter ([username]: [environment name])
Tip: In order find environment names and IDs, execute this API endpoint in Swagger:
The response body will display the name and ID of your current Eclipse environment:
If no such environment exists, a response with aNotFound HTTP status code has to be returned.
If no explicit environment is provided, the first default environment will be chosen. If no default environment exists then the first active non-default environment is chosen. If none of these environment exists, a response with NotFound HTTP status code will be returned.
If the requester is not active in the selected environment, then the system should respond with a Forbidden HTTP status code.
Purpose
In the context of Eclipse PPM, the API provides users with the ability to both access and manipulate Eclipse PPM data outside of the application itself.
APIs are commonly referred to as "windows to the code." They expose some of the program's internal functions to the outside world. This allows applications (such as Eclipse PPM) to share data with other programs without having to share all of its code.
Example: APIs make it possible for big internet services to let other applications use their features. For instance, Yelp uses Google's API to display nearby restaurants with a Google Map:
This is what Eclipse PPM enables its customers to do by "exposing" the Eclipse API: plug Eclipse PPM data into other applications. This is called an integration, and Eclipse PPM customers often do this with applications such as JIRA and Sharepoint so they can access Eclipse data directly within them.
API Endpoints
An API endpoint is one end of a communication channel; when an API interacts with another system, the touchpoints of this interaction are the endpoints. From the endpoint, the API can access the resources required to carry out a particular function. Each Eclipse PPM API endpoint includes the URL of a server or service.
Each API endpoint represents a secure point of access to a particular business entity in Eclipse PPM (Projects, Issues, Risks, Resources, etc.). These endpoints can create, retrieve, update, and delete most of the entities in Eclipse.
As of recently, Eclipse PPM API endpoints are documented online in Swagger. For more information on Swagger, click here.
API Verbs
Eclipse PPM utilizes REST (Representational State Transfer) API, which means that all of the work it carries out can be categorized into four main methods, or "verbs":
GET
A GET is used to retrieve data. When a GET is called, the API works to show you the data you requested.
For example, clicking on a Resource in Eclipse (like the example above) will bring you to the Resource's webpage. When this happens, the API brings all of that Resource's data to that page.
The GET method is sometimes referred to as a "read" because its only job is to essentially "read" data for you; it never actually changes any data.
PUT
A PUT is used to update existing data. In this case, the API will replace the existing resource with the new data included.
For example, you can change the "Planned End" date of a task and save it. When this happens, the API will "put" the new data into the existing resource. Note that when this happens, the webpage URL remains the same. This is because the resource itself remains the same; it has simply been updated to accommodate the new data.
POST
A POST is used to create a new entity. In particular, it creates a new subordinate resource that becomes "posted" to a parent entity.
For example, when you create a new project in Eclipse, the URL looks like this:
In this case, "project" is the existing parent entity and "36196" is a unique project ID that has been posted to it.
DELETE
A DELETE is used to delete an entity identified by the URL.
For example, when you delete a project in Eclipse, the API deletes the unique project ID from the "project" parent resource.
Caution: Once data has been deleted in Eclipse PPM, it is extremely difficult to recover.
Each API endpoint found in the Eclipse PPM documentation in Swagger has one of the four HTTP verbs attached to it. This, along with the endpoint description, will let you know what the endpoint does.
Example: This endpoint is classified as a PUT, which means it can be used to update existing Eclipse PPM data. The description on the right-hand side specifies that it can update project information.
For more information on Eclipse PPM API documentation in Swagger, click here.
API Body
While API endpoints are the touchpoints that applications use to communicate with one another, the API body is the message that travels between them. When data needs to be sent (either through a PUT or a POST) to the API, the data is disclosed into a request body.
Example: In order to POST a new Resource into Eclipse, you must enter the new Resource's data into the request body:
This data then travels through the API and gets "POSTed" to Eclipse PPM.
Note: As displayed in the example above, each API endpoint in the Swagger documentation features an editable request body that allows you to simply enter the data before calling the API endpoint. For more information on Swagger, click here.
Once an API call is made, a response body that contains any requested data will be returned.
Example: Once a successful GET call is made for an Eclipse PPM Resource, you can find all the requested data in the response body: