Why Design-First API’s Fail

You have most likely heard many api people touting the benefits of design first vs code first with people like myself shouting back ‘SECURITY FIRST’.

Well what does that argument mean : design first vs security first?

Well to understand that, you have to understand why design docs like OpenApi do not cover security.

No Rbac/Abac

In the immortal words of Darrel Miller, the lead of the OpenApi project:

No ROLES mean that everyone accesses (and returns data from) the endpoints the same. This is not the case in API’s at all. An while an ADMIN and a USER can have the same access, they do NOT send or receive the same data.

Openapi acknowledges that they cannot do this.

Cookies

OpenAPI does not cover cookies well and while Swagger can handle it in the response, the is no mention anywhere of passing a cookie with request (which is VERY common).

For example, in a typical curl call, you will want to pass the cookie in order to maintain ‘session’:

curl -v -c ./cookies.txt -X GET http://localhost:8080/hello

Openapi has no way to portray this.

No Internal Redirects

And you all may have heard of the incident where OpenAPI maintainers thought that ‘internal redirects’ was a made up term???

Well it required Roy Fielding jumping in and saying that they have existed since the very first HTTP server.

Conclusion

With a ‘design first’ mentallity, you will skip several crucial pieces to your api backend… leaving you vulnerable to bad assumptions and routing exploits.