Bugzilla – Full Text Bug Listing
| Summary: | Define new Api specifications for Eclipse Marketplace REST API | ||
|---|---|---|---|
| Product: | Community | Reporter: | Christopher Guindon <chris.guindon> |
| Component: | Marketplace | Assignee: | Marketplace Inbox <marketplace-inbox> |
| Status: | RESOLVED FIXED | QA Contact: | |
| Severity: | normal | ||
| Priority: | P3 | CC: | leif.geiger, reckord, Ted.Epstein |
| Version: | unspecified | ||
| Target Milestone: | --- | ||
| Hardware: | PC | ||
| OS: | Mac OS X | ||
| Whiteboard: | |||
|
Description
Christopher Guindon
(In reply to Christopher Guindon from comment #0) > Our current API for Eclipse Marketplace is starting to be outdated: > https://wiki.eclipse.org/Marketplace/REST > > In Q2-2019, we would like to define the new Api specification for Eclipse > Marketplace for Eclipse Marketplace. > > The current plan is to submit a pull request to > https://github.com/EclipseFdn/api.eclipse.org-docs. > > At the same time, we would like to investigate and test https://swagger.io/ > and perhaps we will consider migrating our documentation from Blueprint to > Swagger. Hi Christopher, As it happens, you have a Marketplace solution provider with a full-featured, Eclipse-based application for REST API specification and documentation with the Swagger-OpenAPI specification language. :-) https://marketplace.eclipse.org/content/reprezen-api-studio Happy to help with this. If you're interested, could I suggest a real-time conversation to fill in the background, and get a clearer sense of what you'd like to accomplish with the Marketplace REST API and API docs, going forward? Ted Epstein, CEO RepreZen -- ted.epstein@RepreZen.com (In reply to Theodore Epstein from comment #1) > (In reply to Christopher Guindon from comment #0) > > Our current API for Eclipse Marketplace is starting to be outdated: > > https://wiki.eclipse.org/Marketplace/REST > > > > In Q2-2019, we would like to define the new Api specification for Eclipse > > Marketplace for Eclipse Marketplace. > > > > The current plan is to submit a pull request to > > https://github.com/EclipseFdn/api.eclipse.org-docs. > > > > At the same time, we would like to investigate and test https://swagger.io/ > > and perhaps we will consider migrating our documentation from Blueprint to > > Swagger. > > Hi Christopher, > > As it happens, you have a Marketplace solution provider with a > full-featured, Eclipse-based application for REST API specification and > documentation with the Swagger-OpenAPI specification language. :-) > > https://marketplace.eclipse.org/content/reprezen-api-studio > > Happy to help with this. If you're interested, could I suggest a real-time > conversation to fill in the background, and get a clearer sense of what > you'd like to accomplish with the Marketplace REST API and API docs, going > forward? Hi Theodore, We are definitely looking for help and feedback from the community for this new API and your proposition sounds appealing to me! Would you consider a call in mid march to discuss what we are planning to accomplish our new Marketplace REST Api? After our chat, I had a look at Blueprint, and it looks pretty good as well. In fact, the Markdown files and MSON object descriptions are much more readable than the OpenAPI JSON/YAML. I read that there might be some differences in expressiveness, but I don't know if those would affect us. Other than that, I think Blueprint is actually nicer from a documentation standpoint. What's nicer about OpenAPI (Swagger was the previous name and is still the product name for some services offered on top) is that there is a lot of tool support to work with the specification, like mock servers, request/response validators, integration with various test libraries, etc. Blueprint has a number of tools as well at https://apiblueprint.org/tools.html. But many projects seem to be either abandoned or have actually moved to OpenAPI. > We are definitely looking for help and feedback from the community for this > new API and your proposition sounds appealing to me! > > Would you consider a call in mid march to discuss what we are planning to > accomplish our new Marketplace REST Api? Mid-March is good timing. Please feel free to drop a meeting on my calendar whenever you're ready: https://secure.scheduleonce.com/TedEpstein And I'll make a note to follow-up in a couple of weeks if I haven't heard from you by then. Cheers, Ted (In reply to Carsten Reckord from comment #3) > After our chat, I had a look at Blueprint, and it looks pretty good as well. API Blueprint is primarily supported by Apiary, now part of Oracle. MuleSoft's RAML and RepreZen's own RAPID-ML language are all capable of describing REST APIs. Each has some appealing features, and it's beneficial for each of us as technology vendors to be able to drive innovation independently. But there's also a lot of benefit to having an industry standard, and to providing transformations between the standard format and vendor-specific languages. So the industry has converged around OpenAPI. All of us - MuleSoft, Oracle, RepreZen, and many others - have joined the OpenAPI Initiative, formed under the Linux Foundation, and we're gradually incorporating some of the ideas from other API specification languages into OpenAPI. https://www.openapis.org/membership/members > What's nicer about OpenAPI (Swagger was the previous name and is still the > product name for some services offered on top) is that there is a lot of > tool support to work with the specification, like mock servers, > request/response validators, integration with various test libraries, etc. That's right. Also integration with API gateways, API management platforms, code generators, catalogs, integration platforms, documentation formats, and more. You get the idea. To clarify Swagger vs. OpenAPI: 'Swagger' started as a collection of open source projects, including the Swagger UI, an interactive documentation format with integrated sandbox testing via the 'try it out' button. Other Swagger projects include integration libraries for various languages, a code generator, the Swagger specification language, and an editor for Swagger documents conforming to that language spec. 'OpenAPI' refers specifically to the API description language. When SmartBear acquired Swagger several years ago, they started the OpenAPI Initiative with several other founding members and donated the language specification in order to form a true open standard. So 'Swagger' is now a brand name for SmartBear's commercial and open source technologies that work with the OpenAPI standard. Cheers, Ted Quick update: We've made some great progress with OpenApi this quarter. A big thank you to @Ted for helping us out! Your work and feedback pushed us in the right direction. The specification is still a work in progress but we are currently working in a public git repository: https://github.com/EclipseFdn/marketplace-rest-api-specs A draft version of the spec is also available in html: https://eclipsefdn.github.io/marketplace-rest-api-specs/ The next step is to discuss the current state of the documentation with the MPC team to finalize the requirements. Once the specs has been approved by all stakeholders, we will start working on the implementation! If you are interested in contributing to our specs, feel free to open an issue or submit a PR! I am closing this issue! Issues and conversion for this project should now be done on github: https://github.com/EclipseFdn/marketplace-rest-api-specs |