Requesting your feedback regarding - MicroProfile API Tutorial (Preface, Chapter 1, & Chapter 2)

[Tarun Telang]

Hello MicroProfilers, 

Kindly review and share your feedback, inputs or suggestions as comments directly to this Document containing the draft Chapters of the Official MicroProfile Tutorial. This tutorial is designed to empower Java developers across all levels with the necessary knowledge and practical experience to master the MicroProfile specifications. The concepts are demonstrated with the help of a sample project involving the development of microservices-based e-commerce applications.

- Front Matter - https://docs.google.com/document/d/1ZKZ_HGTGNApNh5zPztC6sIo9i4uQQo3Z4awux2_cNpg/edit?usp=sharing

Sections include:  Legal, About this Tutorial, Who is this Tutorial for, What will be covered, Project, Downloading the Code, Prerequisites, Learning Objectives, Conventions

- Chapter 1: Introduction to MicroProfile - https://docs.google.com/document/d/1vfiuCjrFdaPb-PnN8kNgSZtvvHg4oLvmST-LcVAgE70/edit?usp=sharing

Sections include: What is MicroProfile, Need for MicroProfile, MicroProfile Specifications, Current MicroProfile Implementations, Architecture Philosophy, Benefits of MicroProfile, Relationship with Jakarta EE Specification

- Chapter 2: Getting Started with MicroProfile - https://docs.google.com/document/d/1e37CLbD_ajm69TWSDNm6PXr9tlhMfdDwjV93RV1tr3A/edit?usp=sharing

Sections include: Development Environment Setup, Build Tools, Integrated Development Environments, Setting up MicroProfile Runtime, MicroProfile Starter, Creating a Java Project, Creating a REST Resource.

Thanks in advance for your time and effort in reviewing the content. Please feel free to add your comments directly on the Google Docs. I look forward to your valuable feedback to enhance the quality and clarity of this tutorial.

Best Regards,

Tarun

On Tue, 6 Feb 2024 at 14:00, Tarun Telang <tarun....@gmail.com> wrote:

Hi John, 

Now, I have enabled Discussions and Issues in my repo. For sharing the feedback, I suggest the following: 

1. You can create a new issue and attach a word document with detailed line by line feedback.

https://github.com/ttelang/microprofile-tutorials/issues

2. For suggestions / ideas or general discussions you can use this

https://github.com/ttelang/microprofile-tutorials/discussions/categories/ideas

3. If you want, I can also generate a word document for the chapter after completion and upload it to the Google Drive workspace for comments.

Best Regards,

Tarun

On Tue, 6 Feb 2024 at 04:46, John Clingan <jtcl...@gmail.com> wrote:

Thanks, Tarun! I wanted to comment on specific lines or paragraphs. How would you like us to do that? Create a pull request? Feels kinda heavyweight.

On Sunday, February 4, 2024 at 5:48:45 PM UTC-8 tarun....@gmail.com wrote:

Dear MicroProfile Community Members,

I'm reaching out to get your feedback for the MicroProfile API Tutorial for Java developers, a hands-on guide to understanding and working with MicroProfile APIs.

Please find the outline of the MicroProfile Tutorial below for your review.
https://docs.google.com/presentation/d/1whbFxay-emqkeMiKdJh2bp6doiVvRfW0oXG_QYRtaTs/edit?usp=sharing
We're particularly interested in feedback on the tutorial's structure, level of detail, and clarity for both beginner and experienced MicroProfile developers.

Please take a moment to go through it and provide any feedback, suggestions, or comments you may have. Your insights will help us tailor the tutorial to better serve MicroProfile communities' needs.

Thanks and Best Regards
Tarun

--
You received this message because you are subscribed to the Google Groups "MicroProfile" group.
To unsubscribe from this group and stop receiving emails from it, send an email to microprofile...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/0892e976-d71d-473b-af83-9ef5ce0d5364n%40googlegroups.com.

[Amelia Eiras]

Thank you, Tarun, for enabling MicroProfilers' proactive collaboration via Google Documents' suggested edits and comments. 

Some of the feedback on Chapter 1 was sent today. 🙏

Amelia Eiras 

http://tomitribe.com   

To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/CACiDks1R%2B6tXP%3DGEdmq5ZDmzsQdXosF_EopHSN_zJ0vBVLoVGQ%40mail.gmail.com.

[Emily Jiang]

Thank you Tarun! A few of us have provided some feedback via the PRs. Nothing major! Great work!

Thanks

Emily

To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/CAJ0g8j5zqqKmstkisBEVGpZtEh9gskiojd9NZ-7YFnfoYfkB3w%40mail.gmail.com.

--

Thanks
Emily

[Tarun Telang]

I took care of the feedback. Thanks everyone, kindly merge these PRs.  

Best Regards,

Tarun

To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/CAECq3A__FVrH%2BH01gKVvmkavduVBW9%3DsTNzZxPGQyx7Mkjt1tQ%40mail.gmail.com.

[Tarun Telang]

Hello MicroProfilers, 

Kindly review and share your feedback, and suggestions on this Document. 

• Chapter 3: Jakarta EE Core Profile
  Sections include: Understanding the Jakarta EE 10 Core Profile, Key Specifications in Core Profile, Managing Component Dependencies, Handling HTTP Methods and Resources.

It would be great if you can do this in the next 72 hours, so that we can get this  merged to github repo soon.

Best Regards,

Tarun

[Tarun Telang]

Dear MicroProfile Community Members,

Kindly review and share your feedback, and suggestions on Chapter 4 of the MicroProfile Tutorial.

• Chapter 4: MicroProfile OpenAPI (Sections include: Introduction to MicroProfile OpenAPI, API Specification using MicroProfile Open API, Generating API Documentation, Exploring the APIs using Swagger UI)

It would be great if you can do this in the next 72 hours, so that we can get this merged to github repo soon.

Best Regards,

Tarun

[Tarun Telang]

 - Updating the link 

Dear MicroProfile Community Members,

Kindly review and share your feedback, and suggestions on Chapter 4 of the MicroProfile Tutorial.

• Chapter 4: MicroProfile OpenAPI (Sections include: Introduction to MicroProfile OpenAPI, API Specification using MicroProfile Open API, Generating API Documentation, Exploring the APIs using Swagger UI)

It would be great if you can do this in the next 72 hours, so that we can get this merged to github repo soon.

Best Regards,
Tarun

[Tarun Telang]

Hello Everyone, 

Kindly review and share your feedback, and suggestions on Chapter 4 & 5 of the MicroProfile Tutorial.

• Chapter 4: MicroProfile OpenAPI (Sections include: Introduction to MicroProfile OpenAPI, API Specification using MicroProfile Open API, Generating API Documentation, Exploring the APIs using Swagger UI)

• Chapter 5: MicroProfile Configuration (Sections Include: Understanding MicroProfile Configuration, Different environments required for Microservices development, Working with Various Configuration Sources, Key capabilities of MicroProfile Configuration, Implementing Configuration Properties, Creating a Custom Configuration Source, Dynamic Updates and Handling Configuration Change Events, Managing Configuration for Different Environments, Securing Configuration and Best Practices)

After 3 working days, the documents would be merged to /eclipse/microprofile-tutorial.

  

Best Regards,

Tarun

[Tarun Telang]

Hello Everyone, 

Kindly review and share your feedback, and suggestions on Chapter 6 of the MicroProfile Tutorial.

• Chapter 6: MicroProfile Health (Sections: Overview of MicroProfile Health, Types of Health Checks, Standard Health Checks, Implementing and Exposing Health Checks, Logging and Reporting Health Checks, Best Practices for Effective Health Checks)

[John Clingan]

Sorry, I am out on business travel but I do plan to review again early (mon/tue) next week.

[Tarun Telang]

Hello Everyone, 

Kindly review and share your feedback, and suggestions on Chapter 7 of the MicroProfile Tutorial.

• Chapter 7: MicroProfile Metrics (Sections: Introduction to MicroProfile Metrics, Need for Metrics in Microservices
  Types of Metrics, Adding MicroProfile Metrics Dependency, Metrics Annotations, Using Metadata with Metrics, 
  Categories of Metrics, Metric Registry, Instrumenting Microservices with Metrics, Creating Custom Metrics)

[Tarun Telang]

Hello Everyone, 

Kindly review and share your feedback, and suggestions on Chapter 8 of the MicroProfile Tutorial.

Chapter 8: MicroProfile Fault Tolerance (Sections: What is Fault Tolerance?, Key Strategies for Enhancing Fault Tolerance, Implementing Retry Policies and Configuration, Avoiding and Managing Cascading Failures, Configuring Circuit Breaker, Setting Timeouts, Implementing Fallback Logic, Isolating Resources for Fault Tolerance)

  

Best Regards,

Tarun

[Tarun Telang]

Hello MicroProfile Community Members, 

Kindly review and share your feedback, and suggestions on Chapter 9 of the MicroProfile Tutorial.

Chapter 9: MicroProfile OpenTelemetry (Sections: Introduction to MicroProfile OpenTelemetry?, Tracing Concepts (Spans, Traces and Context Propagation), Instrumenting OpenTelemetry, Setting up Tracing  Providers, Context Propagation and Correlation, Analyzing Traces, Security Considerations for Tracing)

It would be great if you can do this in the next 72 hours, so that we can get this merged to github repo soon.

Best Regards,

Tarun

[John Clingan]

This looks really good! I made a couple of comments, and had to delete them when I realized that you covered them in the summary :-)

To view this discussion visit https://groups.google.com/d/msgid/microprofile/CACiDks1H6kEs91ghtMbupNpz-ZCMjzw2YNPQkQ8UrBN5E%2Bh%3DJg%40mail.gmail.com.

[John Clingan]

Sorry, I was referring to Fault Tolerance.

[Tarun Telang]

Hello, 

After incorporating some review feedback, I have created a PR for merging Chapter 09: MicroProfile Telemetry here (https://github.com/eclipse/microprofile-tutorial/pull/18). Kindly review and provide any further feedback before it gets merged.

Best Regards,

Tarun

To view this discussion visit https://groups.google.com/d/msgid/microprofile/5ee3c068-fec6-462c-8fe4-489f1b23cf74n%40googlegroups.com.

[Tarun Telang]

Hello MicroProfilers, 

Updating the Subject of this email. 

Here is the revised list of sections after changing `OpenTelemetry` to `Telemetry` as appropriate based on feedback so far. 

Chapter 9: MicroProfile Telemetry (Sections: Introduction to MicroProfile Telemetry?, Tracing Concepts (Spans, Traces and Context Propagation), Instrumenting Telemetry, Setting up Tracing  Providers, Context Propagation and Correlation, Analyzing Traces, Security Considerations for Tracing)

Best Regards,

Tarun

On Mon, 13 Jan 2025 at 13:02, Tarun Telang <tarun....@gmail.com> wrote:

Hello MicroProfile Community Members, 

Kindly review and share your feedback, and suggestions on Chapter 9 of the MicroProfile Tutorial.

Chapter 9: MicroProfile Telemetry (Sections: Introduction to MicroProfile OpenTelemetry?, Tracing Concepts (Spans, Traces and Context Propagation), Instrumenting OpenTelemetry, Setting up Tracing  Providers, Context Propagation and Correlation, Analyzing Traces, Security Considerations for Tracing)

[Tarun Telang]

Hello MicroProfile Community Members, 

Kindly review and share your feedback, and suggestions on Chapter 10: MicroProfile JWT Authentication of the MicroProfile Tutorial.

Chapter 10: MicroProfile JWT Authentication (Sections: Introduction to JWT Authentication, Understanding JSON Web Tokens, Request Flow, Obtaining and Validating JWT Tokens, Defining User Claims and Scopes in JWT, Role-Based Access Control (RBAC), Setting Token Expiry Times for Security, Implementing Token Refresh for Long-Lived Sessions, Integration with Identity Providers (e.g. OAuth, OpenID), Error Handling, Security Considerations, Auditing and Monitoring, Best Practices for JWT Authentication)

 

It would be great if you can do this in the next 72 hours, so that we can get this merged to github repo soon.

Best Regards,

Tarun

Chapter 10: MicroProfile JWT Authentication

[Sergey Beryozkin]

Hi

On Mon, Jan 27, 2025 at 3:49 AM Tarun Telang <tarun....@gmail.com> wrote:

Hello MicroProfile Community Members, 

Kindly review and share your feedback, and suggestions on Chapter 10: MicroProfile JWT Authentication of the MicroProfile Tutorial.

Chapter 10: MicroProfile JWT Authentication (Sections: Introduction to JWT Authentication, Understanding JSON Web Tokens, Request Flow, Obtaining and Validating JWT Tokens, Defining User Claims and Scopes in JWT, Role-Based Access Control (RBAC), Setting Token Expiry Times for Security, Implementing Token Refresh for Long-Lived Sessions, Integration with Identity Providers (e.g. OAuth, OpenID), Error Handling, Security Considerations, Auditing and Monitoring, Best Practices for JWT Authentication)

I believe I provided comments to this section before and I recall that, IMHO, some of these topics were out of scope, as far as the MP JWT spec is concerned:

* Implementing Token Refresh for Long-Lived Sessions

One can't refresh bearer access tokens, such tokens can only be refreshed at the point where they are acquired and where refresh tokens are available, MP JWT implementations are receivers of the bearer access tokens only

*Integration with Identity Providers (e.g. OAuth, OpenID)

IMHO, this is out of scope, it is too big and wide a topic and MP JWT implementations are only indirectly integrated in some cases, by fetching verification keys sets from such providers.

I'd like to propose dropping these 2 sections.

Thanks

To view this discussion visit https://groups.google.com/d/msgid/microprofile/CACiDks14AeisQz6q2WM-u_-ELG7hGW2QJVJneC%3DrA35O1X9yVw%40mail.gmail.com.

[Tarun Telang]

Hello Sergey, 

Thanks for sharing your feedback and insights again! Yes, we discussed this during the outline review. I will update this chapter as per your suggestions.

Best Regards,

Tarun

To view this discussion visit https://groups.google.com/d/msgid/microprofile/CAMsYBfW_Z5k5OGR03-%3Dwzzm%2BUiiKwD5VFKf9uc-brRqnHACmzA%40mail.gmail.com.

[Sergey Beryozkin]

On Mon, Jan 27, 2025 at 1:17 PM Tarun Telang <tarun....@gmail.com> wrote:

Hello Sergey, 

Thanks for sharing your feedback and insights again! Yes, we discussed this during the outline review. I will update this chapter as per your suggestions.

Thanks, as far as the integration with OAuth2/OIDC providers section is concerned, perhaps it would make sense to re-introduce it once the MP JWT Bridge  is available, bridging MP JWT with Jakarta security which is more OpenID Connect aware, but it is not clear when MP JWT Bridge becomes available, so right now, indeed, it would make sense not to go into this topic while talking about MP JWT alone...

Thanks, Sergey

To view this discussion visit https://groups.google.com/d/msgid/microprofile/CACiDks3e8OQ%2BtEo1Toz1-KOWX1PbEecai7Q-6ZZ08E_ja8YBEg%40mail.gmail.com.

[Sergey Beryozkin]

On Mon, Jan 27, 2025 at 2:10 PM Sergey Beryozkin <sbia...@redhat.com> wrote:

On Mon, Jan 27, 2025 at 1:17 PM Tarun Telang <tarun....@gmail.com> wrote:

Hello Sergey, 

Thanks for sharing your feedback and insights again! Yes, we discussed this during the outline review. I will update this chapter as per your suggestions.

Thanks, as far as the integration with OAuth2/OIDC providers section is concerned, perhaps it would make sense to re-introduce it once the MP JWT Bridge  is available, bridging MP JWT with Jakarta security which is more OpenID Connect aware, but it is not clear when MP JWT Bridge becomes available, so right now, indeed, it would make sense not to go into this topic while talking about MP JWT alone...

I can't comment directly on this section in the doc, so here are a few more comments:

* Creating and Signing JWTs section is not complete, you talk about testing the application with curl, but there is no endpoint code. JWT generation code uses some class to generate the tokens but there is no information about this class (missing import, dependency info), the verification code is similar. 

Perhaps the actual code should not be shown because MP JWT users do not typically verify tokens manually, and rarely create self-issued tokens...

* Symmetric key signature is demonstrated while MP JWT advises asymmetric one only, it is harder to manage the symmetric key distribution

* JWK and JWKS format representations example look incorrect

* There is a section on Jakarta Security but it is unclear how, without MP JWT Bridge, it is relevant

Thanks

[Tarun Telang]

Hello Sergey, 

Thanks once for your valuable feedback and identifying these gaps. 

I have now provided everyone with the commenter access. I will address these gaps and would share the updated draft for your review in the next few days with these changes incorporated.

Best Regards,

Tarun

To view this discussion visit https://groups.google.com/d/msgid/microprofile/CAMsYBfWPBVf_H8XvO%2BD3uzD4YposCwNbMBo6__6rtX_-G-yHNQ%40mail.gmail.com.

[Tarun Telang]

Hello MicroProfile Community Members, 

Kindly review and share your feedback, and suggestions on Chapter 11: MicroProfile REST Client of the MicroProfile Tutorial.

Chapter 11: MicroProfile REST Client (Sections: Introduction to MicroProfile Rest Client, Setting up Dependencies, Defining a Rest Client Interface, Parameter Configuration, Requests and Response Handling, Working with JSON Data format and Error Handling Strategies)

[Arjan Tijms]

Hi,

Tiny thing, but maybe helpful:

> Jakarta Restful Web Services (formerly JAX-RS)

That's formally correct, but we typically use the short name: Jakarta Rest.

> Integration with MicroProfile Fault Tolerance

It's a very good list! Maybe Integration with MicroProfile Long Running Actions is good to mention here too?

> To use MicroProfile Rest Client 3.0 in your project,

and

> For Maven-based projects, add the following dependency to your pom.xml file:

<dependency>
    <groupId>org.eclipse.microprofile.rest.client</groupId>
    <artifactId>microprofile-rest-client-api</artifactId>
    <version>3.1</version>
</dependency>

Seems like a version mismatch there. Maybe just say "To use MicroProfile Rest Client 3.0 in your project"?

> To create a MicroProfile REST Client interface, you need to define a Java interface and annotate it with annotations to map it to a RESTful service. The @RegisterRestClient Annotation
>To use the MicroProfile Rest Client, annotate your client interface with @RegisterRestClient. This annotation registers the interface as a Rest client within MicroProfile runtime and enables it as a CDI bean, allowing it to be injected into other components. 

Looks like the second second rewords the (incomplete) first section?

> 

• The configKey = "product-service" allows configuration via MicroProfile Config (e.g., microprofile-config.properties or environment variables).

The configKey allows easier configuration, right? Without it you can still configure it, but put the fully qualified class name between quotes in the key.

I did really miss some explanation of how the client obtains the proxy, e.g. an example with injecting the Rest client (within an EE/MP runtime), or using RestClientBuilder (in Java SE, or EE/MP).

Hope this helps ;)

Kind regards,

Arjan Tijms

To view this discussion visit https://groups.google.com/d/msgid/microprofile/CACiDks2ZWnJHR6XEYUZUG4FTc%2BDE4Og8a4sxJ8obaYaea%3D%3DuKA%40mail.gmail.com.

[John Clingan]

Thanks Tarun! I'll take a look.

[Tarun Telang]

Hi Arjan, 

Thanks for your detailed feedback! 

I've incorporated your suggestions about fixing version mismatch, mentioning MicroProfile Long Running Actions in Key Features. 

I am currently working on your feedback about adding explanations about how the client obtains proxy and using RestClientBuilder.  

Please also clarify by "how the client obtains a proxy" whether you mean obtaining a Rest Client instance or about obtaining proxy server configuration. 

Thanks and Regards,

Tarun

To view this discussion visit https://groups.google.com/d/msgid/microprofile/CAGZXXA%2Bd-qUv1pUTLe6OdqH9DzBi%3DP%2B-2xRwceFDedoUAoMaLQ%40mail.gmail.com.

[Arjan Tijms]

Hi,

On Tue, 18 Mar 2025 at 12:14, Tarun Telang <tarun....@gmail.com> wrote:

Hi Arjan, 

Thanks for your detailed feedback! 

I've incorporated your suggestions about fixing version mismatch, mentioning MicroProfile Long Running Actions in Key Features. 

I am currently working on your feedback about adding explanations about how the client obtains proxy and using RestClientBuilder.  

Please also clarify by "how the client obtains a proxy" whether you mean obtaining a Rest Client instance or about obtaining proxy server configuration. 

That is about how to obtain the Rest client instance. So by building one programmatically (using RestClientBuilder) or injecting one in a server environment using @RegisterRestClient and then elsewhere @Inject @RestClient.

Kind regards,

Arjan Tijms

 

To view this discussion visit https://groups.google.com/d/msgid/microprofile/CACiDks1NorOiRPJzZPP9qHyypG2PxSpdm_BQFhhzyRR6h%2B9fzQ%40mail.gmail.com.