1

I am looking to add Swagger documentation to my REST APIs but am wondering if it makes sense to add it to all APIs or not. Most of my APIs will only be used by a UI so if I expose for instance a POST endpoint wouldn't it compromise the database with bad data? I have another set of endpoints that I use to upload static data to another 3rd party database system downstream but again I'm having concerns with data pollution. Is this even a valid concern? GETs are the only valid REST verb that I'm seeing potentially exposable.

Additionally, should I even document an endpoint which isn't planned to be used outside a very specific use case?

Improve this question

1 Answer 1

Reset to default
3

Yes, in general you should just the documentation tool cover the entire API. Having exceptions means you then need to maintain all of those exceptions, and humans are prone to error.

If you’re worried about data pollution then you should actually secure your endpoints. Hiding them will not stop a dedicated attacker.

If you’re worried that specialized one-off endpoints aren’t useful, you should reconsider having weird special cases in the same API as your public endpoints.

Improve this answer
7
  • More than an attacker I am concerned with someone just playing with the tool and sending invalid data somewhere where it isn't intended to be sent. Is there a way to control it? The public end points on the service are intended to be public only for the UI and not otherwise. I'm not sure if there is a way to demarcate it.
    – linuxNoob
    Feb 16, 2021 at 22:35
  • 1
    If an endpoint receives invalid data it should detect that and respond appropriately (probably with a 4xx status). You could use tags in swagger to tag endpoints not only by their resources but also with something like "public", that said the beauty of designing a solid REST API backed application is that the UI represents merely one of potentially many consumers and the API is agnostic to them.
    – LJ_1102
    Feb 17, 2021 at 3:33
  • 2
    @linuxnoob - The public end points on the service are intended to be public only for the UI and not otherwise. That is a fairly significant smell. And even if you really need it to work like that, you own the UI. You know what it is allowed to send. Add input validation on your endpoints to toss stuff it shouldn't be sending. Don't trust the front end. Don't trust the user.
    – Telastyn
    Feb 17, 2021 at 4:25
  • 1
    @linuxnoob - by securing (requiring authentication tokens, doing authorization checks) and doing input validation (this field must be positive, that field must not be null) in the service. Rule #1. I’m not sure how to make it more simple.
    – Telastyn
    Feb 17, 2021 at 15:55
  • 1
    @linuxNoob - it is a far better, and more urgent need to get those checks in place first. But it's still a good idea to have Swagger or something in place.
    – Telastyn
    Feb 17, 2021 at 16:08

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.