|
| 1 | +# Overview |
| 2 | + |
| 3 | +This README has the purpose to explain how to setup Postman to use and test our Creme API. |
| 4 | +All the screenshots of this README have been done on Postman Version 9.22.2. |
| 5 | + |
| 6 | +This folder contains: |
| 7 | + |
| 8 | +- 'localhost.postman_environment.json', it is the environment file with all the |
| 9 | +environment variables needed to test Creme API locally, |
| 10 | +- 'Creme_API.postman_collection.json', it is the Postman collection file. |
| 11 | + |
| 12 | +The Postman collection file contains: |
| 13 | + |
| 14 | +- the definition of all the endpoints of Creme API, |
| 15 | +- pre-scripts and test scripts to run automatically tests on all endpoints of Creme API. |
| 16 | + |
| 17 | +# Install and setup |
| 18 | + |
| 19 | +In the following instructions, we will explain to setup your Postman to use Creme API locally. |
| 20 | + |
| 21 | +## Install Postman |
| 22 | + |
| 23 | +First, you need to install Postman on your computer. |
| 24 | +You can use the shop of your system or follow the install instructions of [Postman documentation](https://learning.postman.com/docs/getting-started/installation-and-updates/). |
| 25 | + |
| 26 | +## Import files |
| 27 | + |
| 28 | +After installing Postman, you have to import an environment file and the Postman collection of this folder. |
| 29 | + |
| 30 | +Here are the instruction to import files on Postman. |
| 31 | + |
| 32 | +- On the top right corner of the left panel, click on 'Import' button. |
| 33 | +  |
| 34 | +- A popup will appear and click on 'Upload Files'. |
| 35 | +- Select an environment file, here 'localhost.postman_environment.json', and the 'Postman Collection', and click on 'Import'. |
| 36 | +  |
| 37 | +- Now, if you click on 'Collections' on the left pannel, you will see the 'Creme API' folder and if you click on 'Environments', you will see 'localhost' file. |
| 38 | +- Finally, you have to specify Postman to use the 'localhost' environment variables, by clicking on the top right corner where it's written 'No Environment' and select 'localhost'. |
| 39 | + |
| 40 | + |
| 41 | +## Setup API application |
| 42 | + |
| 43 | +For the last setup part, we have to create an API application on Creme and add the credentials in Postman environment variables. Here are the instructions: |
| 44 | +- go to your [Creme documentation configuration page](http://127.0.0.1:8000/creme_api/configuration), click on 'new application' button and enter all information in the form to create your API application, |
| 45 | +- after saving the form, in the API applications listview, a green popup will appear and you have to note your 'Application ID' and your 'Application Secret'. Watch out this is the only time you will see your 'Application Secret', |
| 46 | + |
| 47 | +- go to your environment file on Postman, add enter your 'Application ID' and your 'Application Secret' in the corresponding variables and click on save. |
| 48 | + |
| 49 | + |
| 50 | +# Usage |
| 51 | + |
| 52 | +This part will explain you how to call an endpoint of Creme API using Postman and how to run tests. |
| 53 | + |
| 54 | +## Postman collection overview |
| 55 | + |
| 56 | +Before using the Postman collection, this section will explain how the collection is structured. |
| 57 | +The collection is organized by entities. In each entity folder you will have all the corresponding available endpoints. |
| 58 | + |
| 59 | +If you click on the main folder 'Creme_API', you will see all the global configuration. |
| 60 | +- In the 'authorization' configuration tab, we select the 'API Key' authentification using an API 'token'. All the childen of the directory will use this authentification, except the 'ask_token' endpoint. |
| 61 | + |
| 62 | +- In the 'Pre-request Script' tab, there are all the JS functions and constants used for the testing part and for calling automatically needed ressources of an endpoint. For example, in the screenshot below, you can see the function that will make Postman ask for you a token if needed. The functions starting by an underscore are internal of this pre-request script config, and the functions in the 'utils' dictionary are used in the 'Pre-request Script' and 'Tests' tabs of the children endpoints. You don't have to modify this pre-request script code. |
| 63 | + |
| 64 | + |
| 65 | +If you click on an entity folder and an endpoint, for example 'Creme_API/Contacts/contact_full_update' you will see: |
| 66 | +- In the 'Params' tab, you have the 'Query Params' and the 'Path Variables'. In the example, we need a 'contact_id', the variable is in red because we don't have yet an 'contact_id' variable, you can put by hand an 'id' of your choice or use the 'Contact/contact_create' endpoint to create and automatically populate the variable. |
| 67 | +- in the 'Authorization' tab, you can see that the endpoint inherits from the parent, so it uses the token authentification, |
| 68 | +- in the 'Headers' tab, we don't have any specific header, |
| 69 | +- in the 'Body' tab, you have an example of body that you can modify to put the information of your choice, |
| 70 | +- in the 'Pre-request Script' tab, we have the code that will be run before making the API call. Here it's call the 'prerequest_script_entity_detail_and_updateviews' function for testing, you can check what it does in the 'Pre-request Script' of the 'Creme_API' folder, |
| 71 | +- in the 'Tests' tab, we have the code that will be run after making the API call. Here it's call the 'test_entity_updateviews_with_addresses' function for testing, you can check what it does in the 'Pre-request Script' of the 'Creme_API' folder. |
| 72 | + |
| 73 | + |
| 74 | +## Call an endpoint |
| 75 | + |
| 76 | +You can use directly the endpoint of your choice, but to start the tutorial, we will ask explicitly a token. Here are the instruction: |
| 77 | +- Click on the 'token' folder, and choose the endpoint 'ask_token'. In the 'Body' tab, you can see that we pass the body the 'application_id' and 'application_secret' we added in the 'localhost' variables before. |
| 78 | +- Click on 'Send'. You will see the response body with the new token in the bottom section of Postman. The 'token' variable will be automatically populate by the received one. |
| 79 | + |
| 80 | +- Click on a folder and the endpoint of your choice, in this example 'Contacts/contact_create'. |
| 81 | +- Click on 'Body' tab, and modify the proposed body with the information of your choice. |
| 82 | +- Click on 'Send'. You will see the response body in the bottom section. You can also see the sent request by clicking on the "code" button on the left panel. |
| 83 | + |
| 84 | + |
| 85 | +## Run tests |
| 86 | + |
| 87 | +You can run the tests on all the collection, just one entity or one endpoint. |
| 88 | + |
| 89 | +To run all the tests, here are the instructions: |
| 90 | +- click on 'Creme_API' folder then on 'Run' button in the top right corner. |
| 91 | + |
| 92 | +- It will open a 'Runner' tab and click on 'Run Creme_API'. |
| 93 | + |
| 94 | +- When it is done, you will have the result of all tests. |
| 95 | + |
| 96 | + |
| 97 | +To run the tests of one entity, click on the folder of the wanted 'entity' and make the same steps as for running all the tests. |
| 98 | + |
| 99 | +To run the test of one endpoint, click on the folder and the wanted endpoint and click on 'Send'. You just have to send the request and the corresponding tests will always be launched. |
0 commit comments