@Jarek your points have fully convinced me. I like the spec first approach
On Sun, Mar 1, 2020 at 2:03 PM Vikram Koka <vik...@astronomer.io.invalid> wrote: > In response to the point raised by Jarek, i.e. 'API first' or 'Code first', > looking at the document, one of the stated goals is: > "The API will be intended for use by any third party. It should not be > related to a specific application, e.g. a React UI" > > In my opinion, the 'Code first' approach only works if the consumers of the > API are all internal to the team or organization. Having a published API > i.e. a well defined interface, is critical for being able to change the > implementation i.e. the code without worrying about impacting the consumer > of the interface. > > Therefore, I recommend the 'API first' approach. > > Vikram > > > On Sun, Mar 1, 2020 at 10:23 AM Ash Berlin-Taylor <a...@apache.org> wrote: > > > On Mar 1 2020, at 5:11 pm, Jarek Potiuk <jarek.pot...@polidea.com> > wrote: > > > At this point you immediately lose all the flexibility that comes with > > "code first" approach: you released the API already and you are not > > supposed to change how the API is designed, yet the design is by-product > of > > the code so it is very difficult to make sure it stays unchanged. You can > > still change the internal implementation but the interface should be > frozen > > anyway. It's much easier if your API definition is your "source of truth" > > rather than code IMHO. > > > > This is a good point and convinces me - API spec first so that API > > changes/tweaks are deliberate sounds like a good way of doing this > (whether > > its v1.1 or v2 is a decision that can be made later). > > Do we need to support multiple versions of API concurrently, or can we > put > > any such requirement on the client(s)? And so long as we have good > > updating/change log for the API versions that seems not too hard a thing > to > > manage. > > -Ash > > > > >
