2
rehman
7y

After how much dev experience you wrote your firs API ?
what are essential steps to write a small good api?

Comments
  • 2
    Hardly any experience haha. The API sucked balls big time though 😄
  • 4
    When it comes to writing a good API, consistency in your response is key! Try to always return the same structure of response so a client implementing your API will always know almost exactly what he or she is getting back
  • 2
    My first api was absolutely rubbish haha 😂

    The most important part of an api is the documentation, as long as it is well documented what a route does and the correct inputs and outputs are clearly explained anyone should be able to use it :)
  • 2
    1. There are GET / POST / DELETE / PUT for a reason, use the right one!
    2. Return correct HTTP status codes! Don't return a 200 and success/error in the response body
    3. If your application is multi-language and you need to return messages, return the translated string AND a clear, unique translation key
    4. If the language you are using supports that, render your documentation from the source code (for request & response models). Outdated documentation is almost as bad as not having any.
    5. If your API does not need authentication: use live examples, which live-queries your API
    6. If you DO have authentication, use cookies/headers for it, not a query parameter
    7. Pretty-print JSON responses if it is sufficiently fast in your language - being able to simply open GET endpoints in the browser is priceless!
    8. Be consistent and predictable - users should be ABLE to look something up in your documentation, not REQUIRED to because they are confused

    Enjoy! Designing a good APl can be fun! :)
  • 0
    Why does everybody simply assumes that it's about webdev?

    I attempted to write a wrapper for the Win32 API to be used with C++ (because I'm not a fan of MFC)

    I couldn't even make a Window show up ._.
  • 0
    I would never recommend writing an API until you are at the very least proficient in the language.
  • 0
    @hawkes I usually return ' success ' And ' error ' while doing stuff in ajax.
    returning HTTP codes like 404 works better ?
  • 1
    @rehman It helps a lot when you adhere to standards.
    As a weird example, you could use CURL on your API and not have to parse the response, as curl returns nonzero on HTTP error codes.
    Or if you need to aggregate data from your and a second API, you would not have to check for errors in 2 different ways.
    If your API may be used by other developers, it also drastically reduces the WTF factor.
  • 0
    @dayo I have done my first api now I'm gonna write its documentation
  • 0
    @anyone could you please direct me towards well written documentation? I don't already have good English and I think I'll mess standards
  • 0
    https://dev.twitter.com/rest/..., i would post mine up but it is no where as good as this :P
Add Comment