4 ms·

I'm wondering if there's actually a widespread demand/need for public API specs. Contentful's API specification (in the blue print format) has been open for a

I'm wondering if there's actually a widespread demand/need for public API specs. Contentful's API specification (in the blue print format) has been open for a while as a side effect of opening up our documentation. I'm not aware of any user ever using for anything but the generated documentation (and there have been bugs in the past that would have made things like generated test servers break quite nicely). What (potential) use case am I missing?

ewittern 11y ago
What do you think about automatic generation of client-code in various languages? With regards to the bugs, were they a result of the implementation and the specification getting out of sync? Would automatic means for creating / maintaining specs be able to help here?
- 7373737373 11y ago
  I spend the last few weeks trying to find an appropriate SDL for my project but have otherwise no experience in creating APIs. In my opinion, API specs should probably be generated from code and its documentation, and not the reverse. This is because it is the code and not the spec which is subject to most change and only the endpoint interfaces/signatures can be generated. API specifications could also be more easily transformed by middleware (e.g. when renaming endpoints, combining APIs) if they were machine generated. As was described above, only few people are acquainted with service description languages, and deeper changes in their semantics over time or the choice of an alternative would require a manual rewrite. Also, some SDLs seem to impose their own higher level ontologies and name spaces, which is another major obstacle to usage for simple systems.
  - krsyoung 11y ago
    First, it is too bad that you spent weeks and probably didn't find the "right" solution (because it doesn't seem to exist). Second, I like your enthusiasm for specs from code ... the problem (opportunity?) today is that the specifications intertwine human readable descriptions / summaries with the actual endpoint / payload information. I would hate for my devops pipeline to kick-off because somebody fixed a typo in some human focused in-line documentation. I personally don't think it belongs in the code but absolutely agree with the spirit of your comment (if you keep them separate it is more work and they will get out of sync!). The best luck I have is working within the specification (i.e. Swagger) and avoiding doing things that don't model well. This seems backwards, but for most of the development I've been involved with to date it has served the projects well. Interested if others have had luck embedding API specs into code.
    - ewittern 11y ago
      Mixing code with documentation is one concern. Another issue is that extracting the information needed to create a Swagger from source code is hard, especially when using dynamic languages (JavaScript, Python). One approach is to use dedicated annotators to relate code with parts of an API spec - but then you have the first problem again...
- wing328hk 11y ago
  Re: What do you think about automatic generation of client-code in various languages? Swagger-Codegen (https://github.com/swagger-api/swagger-codegen https://github.com/swagger-api/swagger-codegen) is a pretty mature, free and open-source project for generating API clients (e.g. ObjC, Java, C#, Ruby, Python, etc) and server stubs (e.g. PHP Slim, Java Spring, etc). Please give it a try and let us know your feedback by opening a ticket via https://github.com/swagger-api/swagger-codegen/issues https://github.com/swagger-api/swagger-codegen/issues Disclosure: I'm a top contributor to the project.
allthingsapi 11y ago
As an API provider, would indexing and discovery of your APIs be of value to you? As a developer with discovery may enable synthesis and composition of APIs. Sites like ProgrammableWeb (http://www.programmableweb.com http://www.programmableweb.com) and API Harmony (http://apiharmony-open.mybluemix.net http://apiharmony-open.mybluemix.net) would do better if they could understand what changed and what is available. I lead the API Harmony team at IBM Research and this information would be extremely valuable.

ewittern 11y ago

What do you think about automatic generation of client-code in various languages? With regards to the bugs, were they a result of the implementation and the specification getting out of sync? Would automatic means for creating / maintaining specs be able to help here?

7373737373 11y ago
I spend the last few weeks trying to find an appropriate SDL for my project but have otherwise no experience in creating APIs. In my opinion, API specs should probably be generated from code and its documentation, and not the reverse. This is because it is the code and not the spec which is subject to most change and only the endpoint interfaces/signatures can be generated. API specifications could also be more easily transformed by middleware (e.g. when renaming endpoints, combining APIs) if they were machine generated. As was described above, only few people are acquainted with service description languages, and deeper changes in their semantics over time or the choice of an alternative would require a manual rewrite. Also, some SDLs seem to impose their own higher level ontologies and name spaces, which is another major obstacle to usage for simple systems.
- krsyoung 11y ago
  First, it is too bad that you spent weeks and probably didn't find the "right" solution (because it doesn't seem to exist). Second, I like your enthusiasm for specs from code ... the problem (opportunity?) today is that the specifications intertwine human readable descriptions / summaries with the actual endpoint / payload information. I would hate for my devops pipeline to kick-off because somebody fixed a typo in some human focused in-line documentation. I personally don't think it belongs in the code but absolutely agree with the spirit of your comment (if you keep them separate it is more work and they will get out of sync!). The best luck I have is working within the specification (i.e. Swagger) and avoiding doing things that don't model well. This seems backwards, but for most of the development I've been involved with to date it has served the projects well. Interested if others have had luck embedding API specs into code.
  - ewittern 11y ago
    Mixing code with documentation is one concern. Another issue is that extracting the information needed to create a Swagger from source code is hard, especially when using dynamic languages (JavaScript, Python). One approach is to use dedicated annotators to relate code with parts of an API spec - but then you have the first problem again...
wing328hk 11y ago
Re: What do you think about automatic generation of client-code in various languages? Swagger-Codegen (https://github.com/swagger-api/swagger-codegen https://github.com/swagger-api/swagger-codegen) is a pretty mature, free and open-source project for generating API clients (e.g. ObjC, Java, C#, Ruby, Python, etc) and server stubs (e.g. PHP Slim, Java Spring, etc). Please give it a try and let us know your feedback by opening a ticket via https://github.com/swagger-api/swagger-codegen/issues https://github.com/swagger-api/swagger-codegen/issues Disclosure: I'm a top contributor to the project.

allthingsapi 11y ago

As an API provider, would indexing and discovery of your APIs be of value to you? As a developer with discovery may enable synthesis and composition of APIs. Sites like ProgrammableWeb (http://www.programmableweb.com http://www.programmableweb.com) and API Harmony (http://apiharmony-open.mybluemix.net http://apiharmony-open.mybluemix.net) would do better if they could understand what changed and what is available. I lead the API Harmony team at IBM Research and this information would be extremely valuable.