Review of Scheduler BB API documentation
- Aneta Pałczyńska (Deactivated)
This is a review of the version 1.0.1 that was last modified less than 1 month ago.
Structural problems:
Gitbook
In all of the schemas there aren’t any parameters descriptions - only their data types
“default” response is present in all endpoints, but we should only have success and error responses (and text of a deafult response indicated it’s for errors?)
Why responses are objects inside arrays that are inside arrays? There are no parameters in etiher the first array or the second array, object is their only child.
Github
Empty test.txt file is unnecessary
Endpoints should be in yaml file, not json file
Discrepancies and missing info:
Bodies of requests aren’t in snippets of code (example/schema view), but success responses are. Both Requests and responses should have examples and schemas in snippets of code for readability
All responses should follow content-type “application/json” but sometimes it’s only “json”
Why reponses are described as content-type json, bu in examples are presented as simple strings? They should ba a json with an only parameter that is a string.
API problems:
POST http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//event/new
no headers
error responses lack examples and schemas
body of a request should be in code snippet with an example and a schema with parameters details (like a success response)
What is a default response? - responses should be defined as either success or error responses
PUT http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//event/modifications
no headers
responses lack examples and schemas
body of a request should be in code snippet with an example and a schema with parameters details (like a success response)
What is a default response? - responses should be defined as either success or error responses
lack of content-type for success and error responses
DELETE http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//event
no headers
responses lack examples and schemas
What is a default response? - responses should be defined as either success or error responses
lack of content-type for success and error responses
GET http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//event/list_details
no headers
responses lack examples and schemas
What is a default response? - responses should be defined as either success or error responses
lack of content-type for error responses
content-type for success response is json instead of “application/json”
body should be written as a snippet of code
for GETs parameters usually suffice
POST http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//entity/new
What is a default response? - responses should be defined as either success or error responses
body of a request should be in code snippet with an example and a schema with parameters details (like a success response)
error responses lack examples and schemas
no headers
PUT http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//entity/modifications
What is a default response? - responses should be defined as either success or error responses
body of a request should be in code snippet with an example and a schema with parameters details (like a success response)
no headers
responses lack examples and schemas
lack of content-type for success and error responses
DELETE http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//entity
no headers
responses lack examples and schemas
lack of content-type for success and error responses
What is a default response? - responses should be defined as either success or error responses
GET http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//entity/list_details
why does GET need to send such a long body?
body should be written as a snippet of code
for GETs parameters usually suffice
What is a default response? - responses should be defined as either success or error responses
no headers
error responses lack examples and schemas
content-type for success response is json instead of “application/json”
POST http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//alert_schedule/new
What is a default response? - responses should be defined as either success or error responses
body of a request should be in code snippet with an example and a schema with parameters details (like a success response)
error responses lack examples and schemas
no headers
PUT http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//alert_schedule/modifications
What is a default response? - responses should be defined as either success or error responses
body of a request should be in code snippet with an example and a schema with parameters details (like a success response)
responses lack examples and schemas
no headers
lack of content-type for success and error responses
DELETE http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//alert_schedule
What is a default response? - responses should be defined as either success or error responses
responses lack examples and schemas
no headers
lack of content-type for success and error responses
GET http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//alert_schedule/list_details
why does GET need to send such a long body?
body should be written as a snippet of code
for GETs parameters usually suffice
What is a default response? - responses should be defined as either success or error responses
no headers
error responses lack examples and schemas
content-type for success response is json instead of “application/json”
POST http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//message/new
What is a default response? - responses should be defined as either success or error responses
body of a request should be in code snippet with an example and a schema with parameters details (like a success response)
error responses lack examples and schemas
no headers
PUT http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//message/modifications
What is a default response? - responses should be defined as either success or error responses
body of a request should be in code snippet with an example and a schema with parameters details (like a success response)
responses lack examples and schemas
no headers
lack of content-type for success and error responses
DELETE http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//message
What is a default response? - responses should be defined as either success or error responses
responses lack examples and schemas
no headers
lack of content-type for success and error responses
GET http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//message/list_details
What is a default response? - responses should be defined as either success or error responses
no headers
error responses lack examples and schemas
content-type for success response is json instead of “application/json”
body should be written as a snippet of code
for GETs parameters usually suffice
POST http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//resource/new
What is a default response? - responses should be defined as either success or error responses
body of a request should be in code snippet with an example and a schema with parameters details (like a success response)
error responses lack examples and schemas
no headers
PUT http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//resource/modifications
What is a default response? - responses should be defined as either success or error responses
body of a request should be in code snippet with an example and a schema with parameters details (like a success response)
responses lack examples and schemas
no headers
lack of content-type for success and error responses
DELETE http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//resource
What is a default response? - responses should be defined as either success or error responses
responses lack examples and schemas
no headers
lack of content-type for success and error responses
GET http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//resource/list_details
What is a default response? - responses should be defined as either success or error responses
no headers
error responses lack examples and schemas
content-type for success response is json instead of “application/json”
body should be written as a snippet of code
for GETs parameters usually suffice
GET http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//resource/availability
What is a default response? - responses should be defined as either success or error responses
no headers
error responses lack examples and schemas
content-type for success response is json instead of “application/json”
body should be written as a snippet of code
for GETs parameters usually suffice
POST http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//subscriber/new
What is a default response? - responses should be defined as either success or error responses
body of a request should be in code snippet with an example and a schema with parameters details (like a success response)
error responses lack examples and schemas
no headers
PUT http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//subscriber/modifications
What is a default response? - responses should be defined as either success or error responses
body of a request should be in code snippet with an example and a schema with parameters details (like a success response)
responses lack examples and schemas
no headers
lack of content-type for success and error responses
DELETE http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//subscriber
What is a default response? - responses should be defined as either success or error responses
responses lack examples and schemas
no headers
lack of content-type for success and error responses
GET http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//subscriber/list_details
What is a default response? - responses should be defined as either success or error responses
no headers
error responses lack examples and schemas
content-type for success response is json instead of “application/json”
body should be written as a snippet of code
for GETs parameters usually suffice
POST http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//affiliation/new
What is a default response? - responses should be defined as either success or error responses
body of a request should be in code snippet with an example and a schema with parameters details (like a success response)
error responses lack examples and schemas
no headers
PUT http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//affiliation/modifications
What is a default response? - responses should be defined as either success or error responses
body of a request should be in code snippet with an example and a schema with parameters details (like a success response)
responses lack examples and schemas
no headers
lack of content-type for success and error responses
DELETE http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//affiliation
What is a default response? - responses should be defined as either success or error responses
responses lack examples and schemas
no headers
lack of content-type for success and error responses
GET http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//affiliation/list_details
What is a default response? - responses should be defined as either success or error responses
no headers
error responses lack examples and schemas
content-type for success response is json instead of “application/json”
body should be written as a snippet of code
for GETs parameters usually suffice
POST http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//appointment/new
What is a default response? - responses should be defined as either success or error responses
body of a request should be in code snippet with an example and a schema with parameters details (like a success response)
error responses lack examples and schemas
no headers
PUT http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//appointment/modifications
What is a default response? - responses should be defined as either success or error responses
body of a request should be in code snippet with an example and a schema with parameters details (like a success response)
responses lack examples and schemas
no headers
lack of content-type for success and error responses
DELETE http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//appointment
What is a default response? - responses should be defined as either success or error responses
responses lack examples and schemas
no headers
lack of content-type for success and error responses
GET http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//appointment/list_details
What is a default response? - responses should be defined as either success or error responses
no headers
error responses lack examples and schemas
content-type for success response is json instead of “application/json”
body should be written as a snippet of code
for GETs parameters usually suffice
POST http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//log/new
What is a default response? - responses should be defined as either success or error responses
body of a request should be in code snippet with an example and a schema with parameters details (like a success response)
error responses lack examples and schemas
no headers
PUT http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//log/modifications
What is a default response? - responses should be defined as either success or error responses
body of a request should be in code snippet with an example and a schema with parameters details (like a success response)
responses lack examples and schemas
no headers
lack of content-type for success and error responses
DELETE http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//log
What is a default response? - responses should be defined as either success or error responses
responses lack examples and schemas
no headers
lack of content-type for success and error responses
GET http://ss2.egovstack.net/r1/eGovStack/COM/11222456/SchedulerBB/creg//log/list_details
What is a default response? - responses should be defined as either success or error responses
no headers
error responses lack examples and schemas
content-type for success response is json instead of “application/json”
body should be written as a snippet of code
for GETs parameters usually suffice
Final conclusions:
It would be great to have a Readme file
All parameters follow a common naming convention which is great
In schemas we should not only state the data type of a parameter but also describe their details and purpose
We should follow the standard of having a body of a request in code snippets