Overview #
The FoxPlan API allows developers to integrate FoxPlan’s project management functionalities into their applications. This guide provides a step-by-step approach to effectively use the API for retrieving and managing project data.
First, we will show you the API documentation and sandbox in FoxPlan. And then, we will show you how to use API in a standalone mode.
Disclaimer #
Use of the FoxPlan API is at your own risk. Since all features are available through the API, you have the ability to crash, delete, or corrupt your data. We highly recommend using a test environment initially. Feel free to contact us; we will be happy to assist you with the API implementation to ensure optimal performance and data security.
API documentation within FoxPlan #
Comprehensive Swagger documentation for the API is available in the Admin Menu of your FoxPlan account. Use this resource to explore detailed endpoint specifications and testing options. Since you are logon to the application, all the security part is done for you in Swagger. Security acces will be detailed in the next section.
To access the swagger documentation, go to the “Settings > Workspace” menu and the “API” tab.
API test with swagger #
For example, we will use swagger to get holidays for a resource.
In Swagger go to the API “/api/vacations” and click “Try it out”
You can then enter the email of the resource for whom you want to request holidays and click “Execute”
You will get the corresponding “curl” command, the URL and the response from the server.
Getting Started with API #
Create an API Account in FoxPlan #
FoxPlan API uses token-based authentication. Before making requests, ensure you have a valid API key. You can generate an API key from your FoxPlan account under the API tab.
Enter a name for the account and click “Add API account”. You will get the “Auth ID” and the “Auth token”. You need to copy these two value and keep them safe.
You need to encode the two contanted string “authId:authToken” in “base64”. You can do this with a tool like https://www.utilities-online.info/base64. The result will be used for the Basic authentication to the API below.
Grant access to the API account #
API account will be granted access to the application with specific rights.
Click on “Assign a role” on the previous screen.
Drag and drop the API account “API_FoxPlan” in the right place in order to give it specific access. For instance, you can drop it in “Workspace Manager”.
Your API account is now ready to be used.
Try your API from PostMan #
We will further show you how to use the API with PostMan, in the real life it will be your code which will perform the query.
Get your API Token #
Your first request on the API is to get your Token ID.
Perform a request on the URL : https://app.fox-plan.com/api/auth
With “Authorization = Basic base64” (base64 being the reference from above).
You need to keep the “id_token”. It will be used in Authentication Header to query the API.
Authorization: Bearer id_token
API Request #
Now we are ready to perform the same example as we did in Swagger but this time we will perform the request from PostMan.
Vacation Example #
Get all vacations for a resource #
Retrieve a list of vacations.
- Endpoint: https://app.fox-plan.com/api/vacations
- Method:
GET
- Query Params : nomprenom@domain.com
- Authorization: Bearer id_token
Response Example:
Congratulations, you have successfully retrieved information through the API.
Best Practices #
- Rate Limits: Respect the API rate limits .
- Error Handling: Implement robust error handling to manage responses such as
400 Bad Request
or500 Internal Server Error
. - Data Security: Store API keys securely and avoid hardcoding them in your applications.
Error Codes #
Code | Description |
---|---|
200 | Success |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Resource Not Found |
500 | Internal Server Error |
For additional support, contact our support team.