One swagger.yaml, or many?

Development Architecture
1

Working with the Swagger toolchain, it’s clear that the Open edX APIs are not structured the way Swagger expects. For example, it categories both “/api/badges/v1/assertions” and “/api/bookmarks/v1/bookmarks” into “api”, and “/zendesk_proxy/v0” into “zendesk”.

When generating code with swagger-codegen, I get an “api_api.py” with dozens of endpoints, and a “zendesk_api.py” with two.

Maybe one way to solve this would be to have more than one swagger.yaml file? One for badges v1, one for bookmarks v1, and so on. I need some feedback from people who have used Swagger before. I feel like we are going against the grain in some way, but I’m not sure what is the right way.

1 Like
2

My latest best idea: move the handful of endpoints that don’t start with “/api” so that they do start with “/api”. Then swagger-codegen will categorize by the next word, which will be “bookmarks”, “certificates”, “cohorts”, etc. This will provide a reasonable categorization.

3

This makes sense to me for now. Would the idea be that the old endpoints will point to the new ones or that the old ones would stop existing and we would update any code that uses them?

1 Like
4

After playing with it some more, I think it makes a lot of sense to focus the swagger machinery on only the /api portion of the URL space. This gives us one swagger.yaml file that segregates endpoints in an expected way.

The simplest way to move APIs is to add a new URL route, so that both the old URL and the new URL will work, by invoking the same Python code. Then we can eventually deprecate and remove the old URL.

5

Yep – since APIs can be called by external applications, I think we need to deprecate the old URLs properly before removing them.

6

@nedbat I’m not sure if this goes against the grain, but wouldn’t having separate swagger.yaml files for each application would make this more plugin-friendly? So instead of each installed plugin adding its own (code drift) API endpoints to the config, we could just keep them in the plugins themselves.

7

Hmm, I see what you mean about the pluggable apps. I definitely don’t have a clear picture of the best path. My hope is to merge my current work this week, and then we can continue to iterate on it together.