The ZAP API - moving to OpenAPI
61 views
Skip to first unread message
psiinon
Jul 15, 2019, 6:14:05 AM7/15/19
to OWASP ZAP Developer Group
ZAP has a very powerful API.
The calls are defined in the ZAP code which means we can generate clients in any language we like. This does take some effort to maintain.
Unfortunately we dont have a standard definition for the API, eg in OpenAPI and the documentation leaves much to be desired.
We have some volunteers what are looking at the documentation, so we're hoping that will start improving soon.
The OpenAPI definition is more 'interesting'.
We've decided that we would really like an OpenAPI definition, not least so that client generation becomes something that anyone can generate using standard tools for any language.
We could generate OpenAPI definitions for the existing calls fairly easily, but they wouldnt include the definitions of the structures of the responses.
Those could be added, but that would be a manual task.
Alternatively we could decide to start again and define a V2 API thats completely defined in OpenAPI.
This would be an opportunity to clean up the V1 API and make it more consistent.
It would also be a non trivial amount of work, but hopefully one that many people can work on, including people new to ZAP development.
If we went down this route then we would support both V1 and V2 versions of the API for the foreseeable future.
I would expect a V2 API to be very similar to the current API, with probably a 1 to 1 mapping for most of the calls.
However it would probably be much more REST like, eg making full use of the HTTP methods like GET, POST, PUT, DELETE...
What do you think?
The calls are defined in the ZAP code which means we can generate clients in any language we like. This does take some effort to maintain.
Unfortunately we dont have a standard definition for the API, eg in OpenAPI and the documentation leaves much to be desired.
We have some volunteers what are looking at the documentation, so we're hoping that will start improving soon.
The OpenAPI definition is more 'interesting'.
We've decided that we would really like an OpenAPI definition, not least so that client generation becomes something that anyone can generate using standard tools for any language.
We could generate OpenAPI definitions for the existing calls fairly easily, but they wouldnt include the definitions of the structures of the responses.
Those could be added, but that would be a manual task.
Alternatively we could decide to start again and define a V2 API thats completely defined in OpenAPI.
This would be an opportunity to clean up the V1 API and make it more consistent.
It would also be a non trivial amount of work, but hopefully one that many people can work on, including people new to ZAP development.
If we went down this route then we would support both V1 and V2 versions of the API for the foreseeable future.
I would expect a V2 API to be very similar to the current API, with probably a 1 to 1 mapping for most of the calls.
However it would probably be much more REST like, eg making full use of the HTTP methods like GET, POST, PUT, DELETE...
What do you think?
- Retrofit OpenAPI to the existing ZAP API
- Start a new V2 ZAP API
psiinon
Jul 15, 2019, 6:27:24 AM7/15/19
to OWASP ZAP Developer Group
For those on twitter you can vote via this poll: https://twitter.com/psiinon/status/1150712923498647553
Luigy0x18
Jul 17, 2019, 12:05:17 PM7/17/19
to OWASP ZAP Developer Group
I vote for Starting a new V2 ZAP API
psiinon
Jul 18, 2019, 9:00:40 AM7/18/19
to OWASP ZAP Developer Group
Reply all
Reply to author
Forward
0 new messages