• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

The Design of Web APIs: Do you explain how to use the OpenAPI Specification ?

 
Ranch Hand
Posts: 150
1
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Dear Sir,

Do you give practical insight into how to use the OpenAPI Specification ?

Thanks.

 
Author
Posts: 15
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Hi,

In this book, I describe how to use the OpenAPI specification to design (chapter 4) and document the API (chapter 12) but I do not dive more in how to extensively take advantage of it (code generation, tool configuration, linting, ...) , that is not the purpose of the book which is focusing solely on design. If you want to dive more into this topic maybe you can look at this book https://www.manning.com/books/designing-apis-with-swagger-and-openapi (it does not cover all topics though)

Arnaud

 
ludoviko azuaje
Ranch Hand
Posts: 150
1
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

...that is not the purpose of the book which is focusing solely on design...



I see, your book is not focused on actual implemention or code.

Do you think that most of the time the design of web services has been neglected in favor of (quick) coding ?

To what extent even well established web apis are bad written, in your opinion ?




 
Arnaud Lauret
Author
Posts: 15
  • Likes 1
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Based on my personal experience, design has been most of the time neglected in favor of quick coding. But slowly but surely, things are changing thanks to public APIs offering awesome developer experience with good design and documentation, people start to realize that spending a moment on design (even for private APIs) before actually coding is worth the (very small) overhead. When you balance "a few hours of design" vs "days of hellish web services/apis integrations" (and I do not speak of design evolutions, security flaws, APIs at scale, ...), the choice is easy to make.

Established APIs (such as Twilio or Stripes for example) are usually well designed because if they are not, people do not use them and the companies die. There still be may some that are not that "good" (based on my standards) nowadays (like the AWS APIs or Saleforces ones as far as I remember) but they are still usable and as the providing service has almost no match, they will probably not change. That's for public APIs.

But when it comes to COTS (you know good old corporate software you install on premise), I have never ever seen any COTS company taking care about their APIs, the ones I have seen have always been a total nightmare.
 
Ranch Hand
Posts: 238
1
Python Ruby Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Based on my personal experience, design has been most of the time neglected in favor of quick coding. But slowly but surely, things are changing thanks to public APIs offering awesome developer experience with good design and documentation, people start to realize that spending a moment on design (even for private APIs) before actually coding is worth the (very small) overhead. When you balance "a few hours of design" vs "days of hellish web services/apis integrations" (and I do not speak of design evolutions, security flaws, APIs at scale, ...), the choice is easy to make.



I agree with you, not only  Web API design, Design in general was getting ignored.
 
Those who dance are thought mad by those who hear not the music. This tiny ad plays the bagpipes:
a bit of art, as a gift, that will fit in a stocking
https://gardener-gift.com
reply
    Bookmark Topic Watch Topic
  • New Topic