[Ask NC] What are the biggest API development issues that you face ?

  • Some issues that I face are :

    1. Deciding on a common API structure amongst teams.
    2. Keeping up to date with the changing API structures.
    3. Suggesting modifications to an existing API.
    4. Waiting for backend developers to finish APIs before getting started.
    5. Notifying co-workers of deprecations/breaking changes.

    If yes then How do you tackle these issues in your current work?

  • One thing I might add here: the pain points around documenting APIs, and how people deal with those.

  • We use swagger for documentation purpose. See http://swagger.io/

  • @vivek-ks - Could you elaborate a little on how Swagger helps you in tackling the above issues ?
    I personally don't know how it helps in Notifying collaborators of changes in an API. We still use emails for that.

  • @dhruv-parmar91 Swagger is only used for documenting and publishing API's. Any change still needs to be communicated via email but we only send the live server email link as swagger is embedded into our app.

  • We use readme.io

    I think the biggest issue is to decide on API architecture that is scalable towards future evolution of product. Deprecating API functions is one of the biggest pains for the API users and doing so may break so many products that depend on the API.

    Did you know notCRUD has cool signatures? Use them by going to your User Profile > Edit.

    Personal blog: paraschopra.com/blog/


  • readme.io is used for creating user facing API reference. The pain of keeping teams updated with the API schema changes still remains. Sometime defining a JSON structure is also a pain.

  • I feel most of the times API structures are decided in meetings on whiteboards and it becomes a pain maintaining context across such meetings.
    Also with remote teams the same process is usually done over email.

    Personally I haven't come across any tool which enables the entire team to collaborate on designing the API.

Log in to reply