Documenting API for microservices?


#1

I’m new to API documentation, and I’ve been following the Write the Docs Slack channel for about two months now, reading everything I can get my hands on, and I attended the June WTD meetup in Boston. I’m a technical writer who has taken a couple of programming courses, but that was over ten years ago, so while I’m comfortable reading through code, I am by no means a programmer and I’m not really sure what’s needed here.

I’m trying to come up with a strategy for writing API docs for a microservices architecture. We’ve currently got over 200+ code repos in GitHub, with six main API areas with over 200 APIs to document. The developers have written some documentation in the GitHub wikis, but that’s not really for public consumption. Our microservices are written in several different programming languages (Java, Python, Ruby), which seems to make choosing tools a bit more challenging. I’d really like to work towards an automated solution, where we’re generating at least the Reference doc out of the code.

Is anyone else out there documenting microservices? Any tips or tricks as far as excellent examples of API doc I should look at, blog posts I should read, tool or toolsets I should consider? I’m sure someone else must have already solved these problems, and I’d hate to reinvent the wheel.


#2

Apologies if I start with what might sound like nitpicking, but it looks as though you’re using the terms “API” and “microservice” somewhat interchangeably. Can you say a little more about the critter(s) you need to document? More API? More “microservice”? And if the latter, just what does your team mean by “microservice”? (It’s used to describe so many different approaches to decomposing a monolith …)

Have you got tooling or processes in place for creating/generating API descriptions? (Swagger, RAML, API Blueprint?)

How data-driven are these APIs? (If they’re true APIs …) Or how much are the APIs/microservices exposing complex server objects? This one is important because if the latter, you’re going to need some human intervention to get useful reference doc, although you can undoubtedly generate at least stubs.

Hope it helps – I’d love to read more!

~Jennifer


#3

As I said, I’m brand new to API docs, and I’ve only been at this job about two months, so I don’t know if this is a gap in my understanding, or a problem with the way our code is designed. At previous jobs I’ve worked on products that used a tiered architecture. At this company, we’re using microservices which are new to me (I’m currently reading my way through Building Microservices (O’Reilly) to help me better understand our architecture). Here’s what I can tell you, we’ve got something like 140 code repositories (and the company we just acquired has a similar number), so I’m assuming one per service? But I could be wrong about that. At previous jobs we’ve either either had all the code for a product in a single repo, or had only a handful of repos (for example, for back-end code, one for UI/presentation layer code, etc.).

I haven’t had a chance to look at all of the repos, but it doesn’t seem like all of them have APIs associated with them (or at least not that I’ve been told need to be documented or have any doc in the wiki). I know services need to talk to each other, thus there should be an API for each of those services, so your guess is as good as mine as to how we’ve actually chunked up our code. I’ve got a spreadsheet that lists six major functional areas, which as far as I can tell map to six particular code repos/services. So again, not sure if all those other repos are actual services, and if they are, how they’re talking to each other or where the actual boundaries are for each service. The spreadsheet lists something like 200 APIs (or possibly just individual endpoints, as it lists each CRUD operation as a separate item). I had a white board talk from our architect on my second day, which went completely over my head, where he sketched out the system for me. I need to ask for a repeat performance now that I’ve learned more about our system and I can ask better questions.

From what I can tell from the system diagram I found (which may be out of date) we deploy on at least 8 different databases, and twenty different hosts. So again, not a one-to-one alignment of host to db to service. Five of those hosts have an "https://api.[servicename] URL associated with them. If you’re wondering about where that API for that sixth functional area is, it’s for reporting so I’m assuming that why it doesn’t have its own separate host and DB.

As far as how data driven they are? Some contain quite a bit of data for rather large records (40 - 50 discrete pieces of data in a single API call), others are only passing small bits of data (for a user record we have separate APIs for address, phone, and email).

Not sure if that answers your questions or not?


#4

If it’s a RESTful HTTP API, then https://developer.spotify.com/web-api/endpoint-reference/ is an example of one done well.


#5

If your microservices all talk through REST or REST’ish APIs you might benefit greatly from some of the tools already mentioned (Swagger, RAML, …) but they probably won’t help you with getting an overview of what services actually exist. At this year’s CraftConf Bora Tunca gave a talk where he mentioned something SoundCloud calls a Service Registry, which might help to get a better overview. Sadly, I couldn’t find that talk online but at least his slides are available here :smile:


#6

Hi, if you’re new to (I assume RESTful) APIs,

  1. Try them out. Find an endpoint. Read about RESTs call against that endpoint (sounds like you’ve done so with Mike Admunson’s book). Repeat until you’ve seen the CRUD verbs (Create, Read, Update, and Delete – which in a REST call is really PUT, POST, GET, PATCH, and DELETE).

  2. Find an endpoint in your microservice. Learn about what you can CRUD against that endpoint, and create your own REST call. Sounds like you may have some existing REST calls to help you learn.

2a) Some endpionts include options – some of the ForgeRock endpoints that I work with include filters that support filtering through databases (sounds like your endpoints might have some of those).

  1. Think about the endpoints for your microservice. If you have one endpoint and one service (e.g. a REST call for an email endpoint), you may not need to automate the process. However, you say that you have over 200 APIs – so yeah, automation is probably the only way you can provide full coverage – to find all the endpoints.

  2. Automation – that’s where you’ll find most current discussion. But with the tools available (such as Swagger), you have the opportunity to clarify the purpose of the endpoint, along with options.

Is a tool like Swagger useful for your readers? It depends. If you have input into the JSON or YAML files behind a Swagger implementation, you can help users understand each endpoint and option.

Thanks,
Mike


#7

Hey @jstickler How did you get along with this? I’m specifically writing an article on documenting microservices, and whilst I acknowledge a lot of what is said here, I want to focus more on the nature of microservices and how they can be assembled and used in multiple different ways.


#8

These best RESTful API books might help you.