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?

linuxNoob
  • 183
  • 6

1 Answers1

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.

Telastyn
  • 108,850
  • 29
  • 239
  • 365
  • 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 '21 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 '21 at 03: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 '21 at 04:25
  • @Telastyn so the difference between UI and Swagger is that in the UI the access is controlled - only people with specific roles can access it and perform operations that affect the data but in Swagger I don't see that control. Anyone can go in and send whatever they want. When I say invalid data I mean test data which maybe structurally valid but doesn't mean the prod systems should be updated with it. I am not sure how the service is supposed to toss that. Maybe I'm just missing something simple here. – linuxNoob Feb 17 '21 at 15:28
  • 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 '21 at 15:55
  • @Telastyn fair enough. Is it a good idea to have Swagger documentation if those checks except for input validation aren't in place? – linuxNoob Feb 17 '21 at 15:57
  • 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 '21 at 16:08