Jaxrs-api: Update Scope Statement for Jakarta API for RESTful Web Services Project

[ivargrimstad]

Update the scope statement for the project: https://projects.eclipse.org/projects/ee4j.jakartaee-platform/governance

See https://docs.google.com/spreadsheets/d/1FPLjo_DJDOQngVtdrYgaDk98d9NBG-0ODgdmOG3LOsI/edit?usp=sharing for examples.

[chkal]

Draft:

Jakarta RESTful Web Services(*) provides a specification document, API and TCK for web services following the Representational State Transfer (REST) architectural pattern.

(*) The name may need to change depending on the outcome of #753

The draft of the scope statement is based on the wording in the original project propsal.

Please share your thoughts.

[mkarg]

+1

[spericas]

I'd like to propose a small tweak to make it a bit more clear:

Jakarta RESTful Web Services provides a specification document, TCK and foundational API to develop web services following the Representational State Transfer (REST) architectural pattern.

[mkarg]

+1

[chkal]

@spericas I'm fine with this new version. But I'm curious. Why do you prefer "foundational API" over just "API"?

[spericas]

@chkal Because there are many APIs these days related to the development of web services, but not all of them are core/foundational.

[chkal]

@spericas I'm not sure I fully understand the difference between foundational APIs and other APIs. However, as mentioned above, I'm fine with this version.

@eclipse-ee4j/eclipse-jaxrs Any other thoughts?

[spericas]

@chkal Let me use an example then. OpenAPI is a very useful API to develop services, but it is not foundational. JAX-WS is a foundational API for SOAP-based services in Java as well.

[chkal]

@spericas Thanks for sharing this explanation. OK, so it is actually about low-level vs high-level APIs in some regard? I could argue that Servlet is even more foundational than JAX-RS. However, compared to OpenAPI you are certainly right. But, as mentioned above, I'm fine with this wording.

[andymc12]

+1 - thanks!

[spericas]

@chkal I doubt a lot of people think about Servlets as the foundation to build _REST_ services. IMO, this is the reason why one technology is evolving and the other isn't.

[chkal]

Ok, looks like everyone is happy with the latest draft. So we have a winner:

Jakarta RESTful Web Services provides a specification document, TCK and foundational API to develop web services following the Representational State Transfer (REST) architectural pattern.

[asoldano]

+1

[mkarg]

I have updated https://projects.eclipse.org/projects/ee4j.jaxrs according to the end of our discussion. Everybody please review. :-)

[andymc12]

@mkarg Looks good. Thanks.

[chkal]

@mkarg Perfect! Thanks!

[waynebeaton]

We can derive, then, a scope statement for the specification itself along these lines:

Jakarta RESTful Web Services defines a standard for development of web services following the Representational State Transfer (REST) architectural pattern.

I'm inclined to ask you to include "for Java(R)" in there somewhere (we're seeing this in other scope statements). Or do you believe that it's reasonably implied? What do you think?

[bshannon]

Including "for Java(R)" seems unnecessary, although probably not harmful.

[chkal]

I agree that "for Java" is unnecessary. IMO "Jakarta" implies "Java".

[mkarg]

For sake of not losing even more relationship to the Java platform, I'd like to keep "for Java".