create api documentation code example

Example 1: how do you implement api

My PROCESS TO IMPLEMENT API
First of all
1. Checking API Contract
An API is essentially a contract between the
client and the server or between two applications.
Before any implementation test can begin,
it is important to make sure
that the contract is correct. 
a.	Endpoints are correct,
b.	Resource correctly reflects the object
model (proper JSON/XML structure used in response),
c.	There is no missing functionality
or duplicate functionality, 
d.	Relationships between resources
are reflected in the API correctly. 
Since I have  verified the API contract,
I am ready to think of what and how to test. 
2. Creating test cases
I mostly create the following test case groups:
a.	Basic positive test (happy paths)
b.	Extended positive testing with
optional parameters
c.	Negative testing with 
valid input (trying to add an existing username)
d.	Negative testing with invalid
input (trying to add a username which is null)
e.	Destructive testing 
(sending null, empty string, integer
or other types, odd date format, deleting necessary parameters)
f.	Security, authorization, and
permission tests (sending valid or 
invalid access tokens to permitted or unpermitted endpoints)
3. Executing test cases
For each API request I need to verify some items like:
a.	Data accuracy: Check the request and
response body whether those are as
written on API documentation in terms
of data type and data structure.
b.	HTTP status code: For example,
creating a resource should return 201
CREATED and unpermitted requests 
should return 403 FORBIDDEN, etc.
c.	Response headers: HTTP server 
headers have implications on both 
security and performance.
d.	Response body: Check valid JSON
body and correct field names, types
, and values - including in error responses.
e.	Authorization checks: Check authentication
and authorization
f.	Error messages: Check the error code 
coverage in case API returns any error
g.	Response time: Implementation of response timeout
4. Test flows
We need to implement the next test flow
if previous flow is success:
a.	Single-step workflow: Executing a 
single API request and checking the
response accordingly. Such basic tests
are the minimal building blocks
we should start with, and there’s no
reason to continue testing if these tests fail.
b.	Multi-step workflow with 
several requests: For example, 
we execute a POST request that creates
a resource with id and we then use this
id to check if this resource is present
in the list of elements received by a GET request.
Then we use a PATCH endpoint to update
new data, and we again invoke a GET request
to validate the new data. Finally, 
we DELETE that resource and use GET
again to verify it no longer exists.
c.	Combined API and UI test:
This is mostly relevant to manual testing, 
where we want to ensure data integrity
between the UI and API. We execute requests
via the API and verify the actions through
the UI or vice versa. The purpose of these
integrity test flows is to ensure that although
the resources are affected via different 
mechanisms the system still maintains expected 
integrity and consistent flow.

Example 2: api documentation

Yes we use swagger for our API documentation and this is 
where the description and guidelines of API endpoints are.