search

codebuddies / backend

CodeBuddies back-end
https://codebuddies.org
GNU General Public License v3.0
20 stars 25 forks source link

Use a shared Postman Collection #62

Closed billglover closed 4 years ago

billglover commented 4 years ago

I've noticed a couple of contributors using Postman to test calls to the APIs exposed as part of the CodeBuddies backend. I would like to explore the idea of a shared Postman collection.

Why? By sharing a Postman (or equivalent) collection we should hope to see a couple of potential benefits. We would gain the ability to consistently call the API making it easier to reproduce observed behaviour. We should also expect to see new contributors finding it easier to make calls to the API.

Why now? Contributors have already started building up personal Postman collections. These get harder to merge as the collections grow.

Cost of doing nothing? If we don't adopt a shared collection we would leave it up to contributors to put together a method for making API requests. These could be documented as part of API documentation, or something as simple as a list of cURL commands.

billglover commented 4 years ago

Option 1: Postman offers a free teams collection (25 requests, 25 shared history) (see FAQ).

Option 2: Postman collections can be exported and stored as part of the repository. There is no meaningful limitation to the size of a collection here. However, sharing collections this way can create interesting merge issues if collections IDs change unexpectedly.

Option 3: We document the API, and provide a mechanism for triggering requests using another tool or service.

lpatmo commented 4 years ago

💯I love Postman collections! Feel like there's a small amount of setup involved that we should take care to document, but it's a tool widely used enough in industry that it'll be a great learning experience for those unfamiliar with it. :)

BethanyG commented 4 years ago

Agree that this is an excellent tool for people to learn to use, and much friendlier than cURL. While using the "browsable api" for DRF can work for quick tests (see screengrab below), having something that mimcs a full api call is quite nice -especially for things like JWT tokens.

DRF "browsable api" : image

billglover commented 4 years ago

I'll start a collection, export it and add it to the repo. If this becomes a pain to manage then we can look at alternative ways to share the collection.