11 ms·

Great work Wenbin! What's the hardest part about maintaining this API?

by dtran 6y ago

wenbin 6y ago
Thanks for asking! The hardest part is to make small incremental improvements over a long period of time :) Like most software projects, this API is never a finished product. It's always work-in-progress. Small incremental improvements are not glamorous, typically not newsworthy to share to the public. Some examples of small incremental improvements: 1. Improve API docs. I heard that many API-focused startups have a dedicated team to maintain their API doc page. 2. Dealing with edge cases. As more apps/websites use our API, we'll see some edge cases that we would never know, which could be as simple as adding a data field in the response with 2 lines code change, or changing search index that requires to re-index the whole thing for a few days. There could also be some strange edge cases with billing, e.g. what if a user subscribe to the paid plan, then unsubscribe, then subscribe again, then do something strange, then unsubscribe... 3. Customer support. This involves adding FAQ (tweaking the texts) and preparing email templates to answer frequently asked questions from users. 4. Doing things to keep the service robust & performant, e.g., adding new alerts via Datadog/Pagerduty so we can know what go wrong in time. We also need to have mechanism to be able to know if a particular app sends tons of requests (e.g., send request in an infinite loop) in a short amount of time and we should be able to do something about it (e.g., suspend the account).
- hashamali 6y ago
  Are the docs custom or are you using a third party product? Doesn’t look like Swagger UI or Slate.
  - wenbin 6y ago
    It's built from scratch, which was easier than customizing from some open source projects back then (early 2019). But the doc is codified in openapi format: https://www.listennotes.com/api/docs/#openapi https://www.listennotes.com/api/docs/#openapi So you can feed the openapi spec into other doc viewers, e.g., Postman, or redoc https://listen-api.listennotes.com/api/v2/openapi.html https://listen-api.listennotes.com/api/v2/openapi.html

Great work Wenbin! What's the hardest part about maintaining this API?

by dtran 6y ago

Great work Wenbin! What's the hardest part about maintaining this API?

Thanks for asking! The hardest part is to make small incremental improvements over a long period of time :) Like most software projects, this API is never a finished product. It's always work-in-progress. Small incremental improvements are not glamorous, typically not newsworthy to share to the public. Some examples of small incremental improvements: 1. Improve API docs. I heard that many API-focused startups have a dedicated team to maintain their API doc page. 2. Dealing with edge cases. As more apps/websites use our API, we'll see some edge cases that we would never know, which could be as simple as adding a data field in the response with 2 lines code change, or changing search index that requires to re-index the whole thing for a few days. There could also be some strange edge cases with billing, e.g. what if a user subscribe to the paid plan, then unsubscribe, then subscribe again, then do something strange, then unsubscribe... 3. Customer support. This involves adding FAQ (tweaking the texts) and preparing email templates to answer frequently asked questions from users. 4. Doing things to keep the service robust & performant, e.g., adding new alerts via Datadog/Pagerduty so we can know what go wrong in time. We also need to have mechanism to be able to know if a particular app sends tons of requests (e.g., send request in an infinite loop) in a short amount of time and we should be able to do something about it (e.g., suspend the account).

hashamali 6y ago
Are the docs custom or are you using a third party product? Doesn’t look like Swagger UI or Slate.
- wenbin 6y ago
  It's built from scratch, which was easier than customizing from some open source projects back then (early 2019). But the doc is codified in openapi format: https://www.listennotes.com/api/docs/#openapi https://www.listennotes.com/api/docs/#openapi So you can feed the openapi spec into other doc viewers, e.g., Postman, or redoc https://listen-api.listennotes.com/api/v2/openapi.html https://listen-api.listennotes.com/api/v2/openapi.html