[Paid Services - Documentation by Tarun Telang] MP API Tutorials

[aeiras]

Tracing history via MP forums

• MicroProfile Tutorial Bid Proposal
• Funding MicroProfile Tutorial with 2023 Budget
• 
  [microprofile-wg] MicroProfile tutorial update

[aeiras]

[
Creating the Official MicroProfile Tutorial - Tarun Telang.pdf
Proposal for Creating MicroProfile Tutorial _ Werner Keil.pdf](https://github.com/eclipse/microprofile-marketing/files/13638308/Proposal.for.Creating.MicroProfile.Tutorial._.Werner.Keil.pdf)

[ttelang]

• Attended MP Marketing Call, 11th December 2023 - 11:30 pm -12:00 pm IST, as per request from Reza and Clark
• Attached is the Presentation summarizing my Outline Proposal -
  Outline for the Official MicroProfile Tutorial.pdf
• I would be joining the upcoming MP Community call to get the above Outline further reviewed.
• As recommended in the MP Marketing Call, I would be following format (ASCIIdoc + Antora) as per Jakarta EE Tutorial - https://jakartaee.github.io/jakartaee-documentation/jakartaee-tutorial/current/index.html
• Awaiting contract from Eclipse Foundation to start the work, might need to reconsider the timeline as MPWG is going on holidays. I will update this ticket after signing the contract and will also share queries for the MP Marketing.

[aeiras]

Dear @ttelang,

Thank you for your generosity in attending today's meeting and introducing yourself while enabling many Q&A.

This ticket has now been assigned to you, and you can use it as you see fit. 👍 This community collaborated with another wonderful MicroProfiler on a similar written project 2019- Technical White Paper Pro Bono by Lars RÖWEKAMP! #3 that has about 86 comments. Therefore, ASK AWAY!

Below is the core summary, in addition to your notes above, of today's feedback provided by MicroProfilers:

• MP goes into End of the Year Vacation from December 16th to January 7th.

The milestones listed above should be postponed to ~ one month later to enable MP proactive feedback.

• During the MP Holiday period, The Tutorial contract agreement needs to be signed directly with the EF team. Reza will connect you with the respective EF members via the MPWG forum. Those conversations with the EF are expected to be private. You are most welcome to use this ticket to let us know when the agreements are signed, and you are a GO to initiate your Research, if any, during the Holiday period.

• MPWG Charter should help you navigate your contributions and collaboration with the MP Community. As mentioned today, MP's Openness is 1 of the seven pillars that should be protected while adding value to the ecosystem.

• Your Research on anything MP is most desirable during the MP Holiday. In MP, the source of truth is the Git Repo and the website.

---

Requests @ttelang,

1. Can you please provide your email? Why?

As a follow-up, I created a Google Drive space for you in the MP community folder under MP>Content

• Tarun Teland - Folder
  folder no contains your Tutorial Outline & Proposal
  Yet, you could use it to house any other documentation as you see fit. The folder access is always Public View yet restricted Edit to protect the content.

We need your email to give you Editor's access to own and manage the folder.

---

[ttelang]

@aeiras - thanks for creating the Google Drive space. For granting edit permissions, my email id is: [email protected].

[ttelang]

• I am awaiting the contract, shared my mailing address to Dennis who is drafting the contract.
  -- 12/21 - reviewed draft contract, as a last step awaiting final version for sign off.
  -- 01/06 - I have signed the contract
• Could not join MP Community call as it was scheduled at 1 am (IST) my local time.
• Reze has introduced me to Kito to provide me pointers regarding leveraging Jakarta EE Tutorial.
• Thanks @aeiras for sharing about the earlier project on MP Whitepaper (https://microprofile.io/resources/#white-paper) and related conversations. It definitely gave good clarity about the process for this project.
• I also went through the MPWG Charter and How to create OSS Content Steps looking forward for collaborating on this project as per recommended processes wherever relevant for this project.

[ttelang]

I have shared following queries to Kito via email. While, I am awaiting response, others may also respond here in case any further inputs.

---

I see there are two formats used for Jakarte EE tutorials:
(1) https://eclipse-ee4j.github.io/jakartaee-tutorial/ (Old one)
(2) https://jakartaee.github.io/jakartaee-documentation/jakartaee-tutorial/current/index.html (New one)

1. Is the second one (2) the right format for creating the new Microprofile tutorial ?

I am referring the following repositories and planning to create MicroProfile tutorial on similar lines:

• https://github.com/jakartaee/jakartaee-tutorial
• https://github.com/eclipse-ee4j/jakartaee-examples
• https://github.com/jakartaee/jakartaee-documentation-ui/

From the above repos, I understand that I need to use the following tools to generate the MicroProfile tutorials:

• AsciiDoc (https://asciidoc.org/) - Jan 8, 2024 - finished familiarizing with AsciiDoc Syntax
• Antora (https://antora.org/) - Started setting up Antora environment - I would be using Antora v3.7.1 for organizing the content for this site.

2. Is my understanding correct, kindly correct me or share any further details if I am missing out something.
3. Is there any recommended diagramming tool for creating architecture diagrams?
4. Is there any style guide for architecture diagrams that I should follow?

[aeiras]

@aeiras - thanks for creating the Google Drive space. For granting edit permissions, my email id is [email protected].

Dear Tarun,

Thank you for getting back to me so quickly. Your editor access has been sent this AM. Welcome to MPWG, contributing via Google Drive as well. :)

---

I am glad the extra resources provided via this ticket are valuable to your initial MP research.
You are already helping improve things in MP with the ticket you submitted. Amazing OSS form, Tarum. You got this! :)

---

As we start the MP Holiday brake up until the 8th of January, I wish you a beautiful Holiday and a happy end of 2023!

[ttelang]

Following Items have been discussed so far:

• I will be preparing the MicroProfile Tutorial as per the format -
  https://jakartaee.github.io/jakartaee-documentation/jakartaee-tutorial/current/index.html

• The content would be written as per Jakarta EE Tutorial Style Guide

• Diagrams will be created using draw.io as per the guidelines at this page - [Jakarta EE Tutorial - Creating Diagrams]- https://github.com/jakartaee/jakartaee-tutorial/blob/main/CONTRIBUTING.md#creating-diagrams.

• I am planning to store the assets of the MicroProfile Tutorials in the following repositories:

S.N	Repo	Purpose
1.	https://github.com/eclipse/microprofile-tutorial	Content of the MicroProfile Tutorial
2.	https://github.com/eclipse/microprofile-documentation	Builds documentation site using the Antora Playbook.
3.	https://github.com/eclipse/microprofile-documentation-ui	HTML and CSS assets used for the look and feel of the documentation site.
4.	https://github.com/eclipse/microprofile-examples	Example source code used inside the Tutorial content

• I need to finalize whether 1&4 should be merged or kept separately.

• I would be referring How Antora Works to get started with how Antora orchestrator pulls up the content from different repos and generates the UI with content, search, etc.

Thanks Kito for confirming the format and tools via email and sharing the style guides about writing content and creating diagrams.

I have started organizing the content in this repository, https://github.com/ttelang/microprofile-tutorials - will get this copied to the new repository https://github.com/microprofile/microprofile-tutorials in a weeks time after it gets into decent shape.

[ttelang]

The tutorial will be based will be based on the currently available latest version of MicroProfile 6.1. Let me know in case, anyone has any other opinion or views on this.

[ttelang]

Today (Jan 23, 2024), I attended MP Open API Technical Call today, presented the outline draft document - https://drive.google.com/file/d/1sSy5FyeQM_QYBPWK761XrBAtUtUQx6ye/view?usp=sharing for feedback on the MicroProfile OpenAPI Specification chapter.

Below were some inputs I received:

• Link for the recent API changes for MicroProfile OpenAPI post MicroProfile 5.0
  https://download.eclipse.org/microprofile/microprofile-open-api-3.1/microprofile-openapi-spec-3.1.html#api_changes_31
• For various technical issues or feedbacks, I would be sharing the drafts / outlines in this group - https://groups.google.com/g/microprofile

[Emily-Jiang]

@ttelang Thank you for joining the MP Technical call yesterday and providing an informative update! As promised on the call, when you are ready to get feedback, please email to the following 2 addresses: [email protected], [email protected]

[Emily-Jiang]

This EF issue was raised to get the dedicated microprofile-tutorial repo created.

[ttelang]

Thanks @Emily-Jiang for sharing about MicroProfile google group and working group mailing lists. I have subscribed to these and started a conversation regarding seeking feedback about the MicroProfile API Tutorial. I will engage with these forums for further inputs regularly.

[ttelang]

Please find below my revised plan for completing the MicroProfile APIs Tutorial:

Milestone	Deliverables	Date	ETA
Design	Final Content Outline and Structure	Done
Milestone 1	Draft Completion for Chapters 1	6th Feb 2024	Done
	Draft Completion for Chapters 2	8th Feb 2024	Done
	Draft Completion for Chapters 3	10th Feb 2024	Done
Milestone 2	Draft Completion for Chapters 4	12th Feb 2024	Done
	Draft Completion for Chapters 5	14th Feb 2024	Done
	Draft Completion for Chapters 6	16th Feb 2024	Done
Milestone 3	Draft Completion for Chapters 7	18th Feb 2024	Done
	Draft Completion for Chapters 8	20th Feb 2024	7th March
	Draft Completion for Chapters 9	22th Feb 2024	7th March
	Draft Completion for Chapters 10	24th Feb 2024	8th March
	Draft Completion for Chapter 11	26th Feb 2024	8th March
Milestone 4	Finalized Tutorial	29th Feb 2024	10th March

[ttelang]

I am working on this repo - https://github.com/ttelang/microprofile-tutorials. After the new repo within the eclipse organization is created, I would move the content there.

Update - This is the new repo for MicroProfile tutorial - https://github.com/eclipse/microprofile-tutorial, please watch this for further updates.

[Emily-Jiang]

This EF issue was raised to get the dedicated microprofile-tutorial repo created.

Created another issue to chase up as I might have created the previous issue under a wrong team.

[jclingan]

I am worried about using the MicroProfile starter as the basis for the tutorial. It creates a mess regarding the variability of JDK/MicroProfile Version/Spec support. Some implementations, like Quarkus, focus on its own starter and not the MicroProfile starter because it is more feature-specific to Quarkus.

Maybe a more appropriate approach is for each runtime to provide a CLI, pom.xml, or instructions for project creation. During the development of the tutorial, I suspect each implementation would have to tweak the instructions as we learn more.

[ttelang]

I am worried about using the MicroProfile starter as the basis for the tutorial. It creates a mess regarding the variability of JDK/MicroProfile Version/Spec support. Some implementations, like Quarkus, focus on its own starter and not the MicroProfile starter because it is more feature-specific to Quarkus.

Maybe a more appropriate approach is for each runtime to provide a CLI, pom.xml, or instructions for project creation. During the development of the tutorial, I suspect each implementation would have to tweak the instructions as we learn more.

I attended MP Starter call on 12th Feb 2024. MP6.1 supports is not yet there.

Below is what I am planning to cover.

Introducing readers about generating a new project structure using MicroProfile Starter. Will also add a note like something like below:

IMPORTANT: At the time of writing this tutorial, the latest MicroProfile released version was 6.1. We will not be using MicroProfile Starter to generate the project structure as it does not currently support this version.

[Emily-Jiang]

@ttelang the github repo https://github.com/eclipse/microprofile-tutorial has been created. You can create PRs to move your materials there.

[ttelang]

Kindly review and share your feedback, inputs or suggestions as comments directly to the Google Docs. Below is the list of chapters that are Ready for Review:

• Front Matter - Sections: 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 - Sections: 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 -
  Sections: Development Environment Setup, Build Tools, Integrated Development Environments, Setting up MicroProfile Runtime, MicroProfile Starter, Creating a Java Project, Creating a REST Resource

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

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

• Chapter 5: MicroProfile Configuration - Sections: 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

• 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

• 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

• 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

• 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

• Chapter 10: MicroProfile JWT AuthenticationSections: 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 will update the above list as soon as more Chapters gets ready for review.

[ttelang]

@ttelang the github repo https://github.com/eclipse/microprofile-tutorial has been created. You can create PRs to move your materials there.

@Emily-Jiang - Thanks for getting this repo created. I will start creating PRs in next couple of days for migrating the tutorial content.

We would need 3 more repos as for the MicroProfile API tutorial as mentioned in the table here - #847 (comment)

[Emily-Jiang]

@ttelang the github repo https://github.com/eclipse/microprofile-tutorial has been created. You can create PRs to move your materials there.

@Emily-Jiang - Thanks for getting this repo created. I will start creating PRs in next couple of days for migrating the tutorial content.

We would need 3 more repos as for the MicroProfile API tutorial as mentioned in the table here - #847 (comment)

@ttelang we discussed this at the last Technical call. We agreed to just have one repo microprofile-tutorial. You can add multiple modules in that repo.

[Emily-Jiang]

@ttelang I have the MP Tutorial repo set up for you with Apache License and it is ready for you to create PRs.

[ttelang]

@ttelang I have the MP Tutorial repo set up for you with Apache License and it is ready for you to create PRs.

Hi @Emily-Jiang , I have created the following PRs for your review:

• 9 - Preface (Front Matter) - Merged ✅
• 10 - Chapter 1: Introduction to MicroProfile - Merged ✅
• 11 - Chapter 2: Getting Started with MicroProfile - Merged ✅
• 12 - Chapter 3: Jakarta EE 10 Core Profile - Merged ✅
• 13 - Chapter 4: MicroProfile Open API - Merged ✅
• 14 - Chapter 5: MicroProfile Configuration - Merged ✅
• [15 - Chapter 6: MicroProfile Health]
  (Chapter 6: MicroProfile Health microprofile-tutorial#15) - Merged ✅
• 16 - Chapter 7: MicroProfile Metrics - Merging ✅
• [17 - Chapter 8: MicroProfile Fault Tolerance] (Chapter 8: MicroProfile Fault Tolerance microprofile-tutorial#17) - Final Review
• 18 - Chapter 9: MicroProfile Telemetry - Review

[ttelang]

I am worried about using the MicroProfile starter as the basis for the tutorial. It creates a mess regarding the variability of JDK/MicroProfile Version/Spec support. Some implementations, like Quarkus, focus on its own starter and not the MicroProfile starter because it is more feature-specific to Quarkus.

Maybe a more appropriate approach is for each runtime to provide a CLI, pom.xml, or instructions for project creation. During the development of the tutorial, I suspect each implementation would have to tweak the instructions as we learn more.

The tutorial will take a neutral approach avoid emphasizing any single MicroProfile implementation.

• Examples within the tutorial will be centered around MicroProfile specifications
• We would be sharing only about the minimal pom.xml containing only the MicroProfile dependency for the specifications covered in the corresponding chapter.
• If required, Instructions for using popular implementations (Open Liberty, WildFly, Payara etc.) would be covered in a separate section.
  The complete code listing will be provided in separate repository for e.g. eclipse/microprofile-examples

Collaborating with the MicroProfile community, we can seek links to more in-depth guides provided by the implementations themselves.

[ttelang]

Recorded these videos 🎥 while verifying the content of first three chapters of MicroProfile Tutorial (Milestone 1)

• Installing JDK 17 ▶️ (2 mins)
• Developing a Microservice using Jakarta EE + MicroProfile in GitHub Codespaces ▶️ (20 mins)
• Building RESTful Web Services using Jakarta EE 10 Core Profile, MicroProfile Open API, MicroProfile Config, MicroProfile Health ▶️ (158 mins)

[jclingan]

@ttelang Do you have an update? It's been a while and we haven't seen updates on the Google Docs that we review. Are you waiting on an action item from us?

[croundy]

@ttelang please provide a status update to this issue. Thanks!

[jclingan]

@ttelang We'd like to get an update before the steering committee call on Tuesday.

Thanks!

[jclingan]

@ttelang Ping. Any updates?

[rstjames]

Update from Marketing call Jan 6 2025

Tarun - MPWG Technical Tutorial -
[Paid Services - Documentation by Tarun Telang] MP API Tutorials #847
Chapter 8: MicroProfile Fault Tolerance - Ready for Review
7 chapters are completed in the github
2 chapters are 80% done
2 chapters need to be written that makes up for the 20% of work left to do
11 chapters total
MP Holiday vacation starts on the 16th of December - We are back on January 6th.

[ttelang]

Status Update - 29th January 2025

✅ Chapters 01 - 08: Completed and available in GitHub.
🔄 Chapters 09 & 10: Under review. Currently incorporating feedback from the MP Community.
✍️ Chapter 11 (Final Chapter): Draft in progress. Planning to share for review in the coming days.