feat: update tutorials for Membrane API Gateway #2498
Conversation
- Removed obsolete `membrane.sh` script for REST tutorial. - Enhanced advanced, JSON, and XML tutorials with clearer starting instructions and feature descriptions. - Added new SOAP tutorial, including introductory documentation, configuration (`10-Sample-SOAP-Service.yaml`), and example script (`invoke-sample-soap-service.sh`). - Fixed command inconsistency in `10-PathParameters.yaml`.
- Clarify usage details in `10-Sample-SOAP-Service.yaml`. - Add initial reference to `.yaml` file in the tutorial's `README.md`.
WalkthroughThis PR updates tutorial documentation and adds a new SOAP tutorial module. Changes include standardizing startup instructions across advanced tutorials, restructuring README files for the advanced, JSON, and XML tutorials, introducing a complete SOAP tutorial with configuration file and invocation script, and removing the membrane.sh shell script from the REST tutorials folder. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes
Possibly related PRs
Suggested labels
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
| @coderabbitai review |
✅ Actions performedReview triggered.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
distribution/tutorials/xml/README.md (1)
11-13: Consider removing or relocating the TBD section.The TBD section in user-facing tutorial documentation may create confusion or appear unpolished to users. Consider one of these alternatives:
- Remove the TBD section until XSLT transformation content is ready
- Track it internally (e.g., in a GitHub issue) instead of exposing it in tutorials
- If you want to indicate planned features, rephrase it more positively: "Additional topics coming soon: XSLT transformation"
Option to remove TBD section
- - -## TBD: - -- XSLT transformation
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (8)
distribution/tutorials/advanced/10-PathParameters.yamldistribution/tutorials/advanced/README.mddistribution/tutorials/json/README.mddistribution/tutorials/rest/membrane.shdistribution/tutorials/soap/10-Sample-SOAP-Service.yamldistribution/tutorials/soap/README.mddistribution/tutorials/soap/invoke-sample-soap-service.shdistribution/tutorials/xml/README.md
💤 Files with no reviewable changes (1)
- distribution/tutorials/rest/membrane.sh
🧰 Additional context used
🪛 Shellcheck (0.11.0)
distribution/tutorials/soap/invoke-sample-soap-service.sh
[error] 1-1: Tips depend on target shell and yours is unknown. Add a shebang or a 'shell' directive.
(SC2148)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Analyze (java)
🔇 Additional comments (3)
distribution/tutorials/xml/README.md (1)
1-8: Well-structured tutorial introduction - referenced file confirmed.The XML tutorial introduction is clear and well-organized. The reference to 10-JSON-to-XML.yaml is valid and the file exists in the xml tutorials directory.
distribution/tutorials/advanced/README.md (1)
3-15: Excellent tutorial restructuring with clear prerequisites and starting point.The changes improve the tutorial by:
- Using the full product name "Membrane API Gateway" for clarity
- Establishing a clear prerequisite (Getting Started tutorial)
- Providing a specific starting point (10-PathParameters.yaml)
- Maintaining consistency with the JSON and XML tutorial structure
The Getting Started tutorial path reference is correct.
distribution/tutorials/advanced/10-PathParameters.yaml (1)
8-8: Verify that membrane.sh is accessible from the advanced directory.The startup instruction now uses
./membrane.shas a relative path. Given that the PR removesdistribution/tutorials/rest/membrane.sh, please confirm that:
- The membrane.sh script exists in the
distribution/tutorials/advanced/directory, or- Users are expected to run this command from a different working directory
This ensures the tutorial instructions work correctly for users.
| This tutorial covers working with JSON in Membrane API Gateway, including: | ||
| | ||
| - JsonPath | ||
| - JSON message transformations | ||
| | ||
| To begin, open [10-JsonPath.yaml](10-JsonPath.yaml) and follow the instructions in the file. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash # Check if the referenced file exists fd -t f '^10-JsonPath\.yaml$' distribution/tutorials/json/ # List all YAML files in json directory for context echo "=== All YAML files in json directory ===" fd -t f -e yaml distribution/tutorials/json/Repository: membrane/api-gateway
Length of output: 539
🏁 Script executed:
#!/bin/bash # Check if the referenced file exists using corrected fd syntax echo "=== Searching for 10-JsonPath.yaml ===" fd --full-path '10-JsonPath\.yaml$' distribution/tutorials/json/ # List all files in json directory for context echo "=== All files in json directory ===" fd . 'distribution/tutorials/json/' 2>/dev/null || echo "Directory may not exist" # Check if directory exists echo "=== Checking if distribution/tutorials/json/ exists ===" ls -la distribution/tutorials/json/ 2>/dev/null || echo "Directory does not exist" # List all tutorial directories echo "=== All tutorial directories ===" find distribution/tutorials -maxdepth 1 -type d 2>/dev/null | sortRepository: membrane/api-gateway
Length of output: 1089
Fix referenced YAML filename - file does not exist as specified.
The README references 10-JsonPath.yaml, but the actual file in the directory is 20-JSONPath.yaml. Update the reference to match the correct filename (including the numeric prefix and capitalization).
🤖 Prompt for AI Agents
In distribution/tutorials/json/README.md around lines 3 to 8, the README references a non-existent file name "10-JsonPath.yaml"; update that reference to the correct file name "20-JSONPath.yaml" (matching numeric prefix and capitalization) so the README points to the actual YAML file in the directory. | # 1.) Start Membrane: | ||
| # Open a terminal in this folder and run: | ||
| # | ||
| # Linux/Mac: | ||
| # ./membrane.sh -c 00-First-API.yaml | ||
| # Windows: | ||
| # membrane.cmd -c 00-First-API.yaml |
There was a problem hiding this comment.
Fix incorrect filename references in startup instructions.
The startup commands reference 00-First-API.yaml, but the actual filename is 10-Sample-SOAP-Service.yaml. This will prevent users from starting the tutorial correctly.
🔎 Proposed fix
# 1.) Start Membrane: # Open a terminal in this folder and run: # # Linux/Mac: -# ./membrane.sh -c 00-First-API.yaml +# ./membrane.sh -c 10-Sample-SOAP-Service.yaml # Windows: -# membrane.cmd -c 00-First-API.yaml +# membrane.cmd -c 10-Sample-SOAP-Service.yaml📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| # 1.) Start Membrane: | |
| # Open a terminal in this folder and run: | |
| # | |
| # Linux/Mac: | |
| # ./membrane.sh -c 00-First-API.yaml | |
| # Windows: | |
| # membrane.cmd -c 00-First-API.yaml | |
| # 1.) Start Membrane: | |
| # Open a terminal in this folder and run: | |
| # | |
| # Linux/Mac: | |
| # ./membrane.sh -c 10-Sample-SOAP-Service.yaml | |
| # Windows: | |
| # membrane.cmd -c 10-Sample-SOAP-Service.yaml |
🤖 Prompt for AI Agents
In distribution/tutorials/soap/10-Sample-SOAP-Service.yaml around lines 7 to 13, the startup instructions reference the wrong filename (00-First-API.yaml); update both Linux/Mac and Windows example commands to use the correct filename 10-Sample-SOAP-Service.yaml so users can start the tutorial correctly. | curl -X POST http://localhost:2000/city-service \ | ||
| -H "Content-Type: text/xml" \ | ||
| -H "SOAPAction: https://predic8.de/cities" \ | ||
| -d @- <<'EOF' | ||
| <?xml version="1.0" encoding="UTF-8"?> | ||
| <s11:Envelope | ||
| xmlns:s11="http://schemas.xmlsoap.org/soap/envelope/" | ||
| xmlns:cs="https://predic8.de/cities"> | ||
| <s11:Body> | ||
| <cs:getCity> | ||
| <name>Berlin</name> | ||
| </cs:getCity> | ||
| </s11:Body> | ||
| </s11:Envelope> | ||
| EOF No newline at end of file |
There was a problem hiding this comment.
Add shebang line for portability.
The script is missing a shebang line, which affects portability and clarity about the intended shell interpreter.
🔎 Proposed fix
+#!/bin/bash curl -X POST http://localhost:2000/city-service \ -H "Content-Type: text/xml" \ -H "SOAPAction: https://predic8.de/cities" \📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| curl -X POST http://localhost:2000/city-service \ | |
| -H "Content-Type: text/xml" \ | |
| -H "SOAPAction: https://predic8.de/cities" \ | |
| -d @- <<'EOF' | |
| <?xml version="1.0" encoding="UTF-8"?> | |
| <s11:Envelope | |
| xmlns:s11="http://schemas.xmlsoap.org/soap/envelope/" | |
| xmlns:cs="https://predic8.de/cities"> | |
| <s11:Body> | |
| <cs:getCity> | |
| <name>Berlin</name> | |
| </cs:getCity> | |
| </s11:Body> | |
| </s11:Envelope> | |
| EOF | |
| #!/bin/bash | |
| curl -X POST http://localhost:2000/city-service \ | |
| -H "Content-Type: text/xml" \ | |
| -H "SOAPAction: https://predic8.de/cities" \ | |
| -d @- <<'EOF' | |
| <?xml version="1.0" encoding="UTF-8"?> | |
| <s11:Envelope | |
| xmlns:s11="http://schemas.xmlsoap.org/soap/envelope/" | |
| xmlns:cs="https://predic8.de/cities"> | |
| <s11:Body> | |
| <cs:getCity> | |
| <name>Berlin</name> | |
| </cs:getCity> | |
| </s11:Body> | |
| </s11:Envelope> | |
| EOF |
🧰 Tools
🪛 Shellcheck (0.11.0)
[error] 1-1: Tips depend on target shell and yours is unknown. Add a shebang or a 'shell' directive.
(SC2148)
🤖 Prompt for AI Agents
distribution/tutorials/soap/invoke-sample-soap-service.sh lines 1-15: the script lacks a shebang which reduces portability and clarity about which shell to use; add a shebang as the first line (use a portable form like #!/usr/bin/env bash) so the script runs with the intended interpreter across environments and commit the updated file. 
membrane.shscript for REST tutorial.10-Sample-SOAP-Service.yaml), and example script (invoke-sample-soap-service.sh).10-PathParameters.yaml.Summary by CodeRabbit
Documentation
New Features
✏️ Tip: You can customize this high-level summary in your review settings.