24.1030

This page is a dumpster of notes and possible junk.... moved a lot of stuff here 24.1030.

---

24.1019 (gdrive)

Patterns. Real world simple examples that show what the goal is.

Something like whats below.

---

Be A Better Dev

https://app.eraser.io/workspace/9XoQ8u9WzQsgEVuchk2g

https://youtu.be/bYoSDUkNAaE?t=60

https://www.youtube.com/watch?v=06VgLTqNvU8

All docs referenced on this page available on Gdrive.

The following are the (basic) demos I've gotten to work so far (its a start). I am in the "window shopping phase, experimenting with and documenting any promising API doc tools I can find. Later I will write getting started and conceptual guides based on the best tools.

Part 63.1 contains demos of API creation with NO API docs. Knowing how to create basic APIs is important for creating API docs.

• (OK) *63.3a_#21_(3.0)_flask_rest_api_tutorial_DaveGray_v02_24.0811_0903_0916.docx
• (OK) 63.1_#24_Python_REST_API_Tutorial-Building_a_Flask_REST_API_Tech_With_Tim_v01_24.0915.docx // youtube.com/watch?v=GMppyAPbLYk 20.07, 70mins, sqlalchemy db, copilot guessed much of it
• (OK) 63.1_#4_Create_A_Python_API_in_12_Minutes_Tech_With_Tim_v01_24.0915.docx

• (OK) 63.1a_#30_FastAPI_Introduction_Build_Your_First_Web_App_Python_Tutorial_01_24.0918.docx FastAPI Introduction - Build Your First Web App - Python Tutorial Patrick Loeber https://www.youtube.com/watch?v=0RS9W8MtZe4
• (OK) 63.1_#27_Python_FastAPI_Tutorial_Build_a_REST_API_in_15_Minutes_v01_24.0916.docx Python FastAPI Tutorial: Build a REST API in 15 Minutes pixegami https://www.youtube.com/watch?v=iWS9ogMPOI0

• (OK) (24.01,50mins) (PAYWALL... but good overview) 63.1_#29_Build_APIs_with_Flask_the_right_way_02_24.0918.docx Build APIs with Flask (the right way) microapis https://www.youtube.com/watch?v=mt-0F_5KvQw (NOTE: PUT at the end of demo returned 500.. otherwise all OK)

• (OK) 63.2a.1_#41_swashbuckle_v07_24.0920.docx

• (OK) 63.2b_#34_sphinx_tutorial_WSL_01_24.0920.docx, This is the sphinx website tutorial.. still need to finish. The author for some reason leaves out little critical details left and right, so will take some time. but basically works. WSL win11.
• (OK) (GIT) 63.2b_#33_sphinx_soumil_WSL_01_24.0919.docx Sphinx Documentation Tool | HTML UI | How to Document Large Python Codebases and Classes | Soumil Shah https://www.youtube.com/watch?v=5s3JvVqwESA
• (OK) (WSL) 63.2b_#31_zero2hero_sphinx_WSL_01_24.0919.docx zero 2 hero sphinx https://www.youtube.com/playlist?list=PLMQPLA3qF-uuD2p6s7qEjhIawm8pIqYr-

Deploy = API doc available at URL.

• (OK) 63.5__#51_nodejs_swagger_to_aws_v01_24.0924.docx, deployed swagger (in nodejs) to aws elastic beanstalk.
• (OK) 63.5__#50_swagger_to_gitbook_v01_24.0923.docx, deployed swagger to gitbook.
• (OK) 63.5__#49_swagger_to_railway_v01_24.0923.docx, deployed swagger to https://swaggerrailway-production.up.railway.app/api-docs/ .

• (OK)("90%")(AZURE) 63.5__#53_nodejs_swagger_to_azure_v02_24.0925.docx (my test deployment on azure)
• (OK)(AWS) 63.1__#46_fastapi_ec2_pixegami_v01_24.0922.docx How to Deploy FastAPI on AWS EC2: Quick and Easy Steps! pixegami https://www.youtube.com/watch?v=SgSnz7kW-Ko

• (OK) 63.7_#43_sdk_caleb_v02_24.0921.docx. Create a simple SDK.

• (OK) 63.0a_#44_pypi_v01_24.0921.docx. Publish a PYTHON package to pypi.

This page is a WIP (work in progress). See also ___concepts.docx (outdated) on Gdrive.

This page decribes the main API doc concepts as I understand them (diagrams are my original)

• 1 API doc types
• 2 API doc workflows

For now just quick "napkin" drawings (created 24.0924). Will redo later.

An app contains the code (Fast API, etc) for generating the API (which provides access to app functionality).

The Swagger file is generated from the

• API code (inside the app (not shown in this diagram xxxxxxx))
• Comments inside the code (API description, etc)

The Swagger docs can be created

• manually (diagram below)
• generated from an app like Sphinx (NOT SHOWN IN DIAGRAM XXXXXXXXX)

GraphQL basically does the following (my understanding; if I am correct, then I dont understand why I never seen such a straightforward description anywhere, especially from official GraphQL docs):

• The query tool is used to create a query that specfies a tree of only the objects needed.
• Query is sent to the Apollo server.
• Apollo server executes the REST commands required to get all the required objects.
• Apollo "distills" the content to send back to the query tool

Postman is used to test the API endpoints. Postman is like a browser that allows you to control things "under the hood". Postman can

• Send URL requests like the browser
• View and control request/response parameters (like browser F10 dev tools)
• Main a history of commands (like browser history) and request/response details

Swagger docs can be published by sending to a host server that publishes

• Without app server (for example: Gitbook)
• With app server (such as NPM) (for example: Railway, AWS)

Swagger docs can also be published witin the app deployed on an app server.

• Design APIs first with Swagger before coding (no one does this).

• Create (basic) APIs.
• Create API definitions / schemas from code.
• Publish API docs (hosting sites, Railway, AWS, Gitbook, Heroku, etc).

The following has been the typical workflow for my recent projects:

1. Collect the existing API docs (what little existed).
2. Learn the API hands on (using Postman/Swagger) with minimal assistance.
3. Make my work available internally (usually via simple a tool like a Github wiki).
4. Create hands-on quick start / getting started docs (with examples, examples, examples).
5. Create a conceptual explanation of the big picture.
6. Create a sanitized/obfuscated version of API (generate from code or (my preference) edit the swagger file directly).
7. Publish the API (first internally, then externally) in something like Gitbook, a React app, etc.

The API docs I created provided details about the options, workflows, and prerequisites for endpoints. Documenting special cases that often are difficult to specify with just a swagger file.

All projects were successful. However

• Published output was only made available to customers (not public) or the product failed.
• My working docs were the confidential property of the client.
• I did not record the details of what I did. That last day on the project always came much quicker than I expected.

24.0919 Gdrive

Test with postman.

• (Despa, 2019) Sending GraphQL Queries in Postman Valentin Despa In this video, we take a first look at a totally new feature in Postman 7.2 which allows you to send a GraphQL query using Postman. https://www.youtube.com/watch?v=GLdcIXjkb7k
• tRPC, gRPC, GraphQL or REST: when to use what? Software Developer Diaries https://www.youtube.com/watch?v=veAb1fSp1Lk

24.0920 Gdrive

Note: Make sure that all useful content taken from this:

• 63.2_(1.4)_api_sdk_graphql_v06_23.0901_24.0903_SANITIZED.docx

• *(GIT, 3.5hrs) Build and Deploy a GraphQL API using NodeJS (tutorial for beginners) notJust․dev https://www.youtube.com/watch?v=UYQSVH6B1k4

• ($2, no Gpay) GraphQL Crash Course https://netninja.dev/p/graphql-crash-course
• 63.1b #13 [4] graphql examples (potpourri) 63.2_(1.4)_api_sdk_graphql_v06_23.0901_24.0903_SANITIZED.docx
• 63.1b #19 httpswww.digitalocean.comcommunitytutorialsq=apollo 63.2_(1.4)_api_sdk_graphql_v06_23.0901_24.0903_SANITIZED.docx
• 63.1b #20 hasura.iolearngraphqlintro-graphqlgraphql-mutations 63.2_(1.4)_api_sdk_graphql_v06_23.0901_24.0903_SANITIZED.docx
• *(NetNinja, 90mins) GraphQL Course for Beginners freeCodeCamp.org https://www.youtube.com/watch?v=5199E50O7SI

(was 4b graphql (stepzen/anvil))

• (22.03) 63.3b_#14a_documenting_graphQL_api_stepzen.docx (https://www.youtube.com/@StepZen, IBM company) https://www.youtube.com/watch?v=8Q31P9n0W2Y
  • Build & Deploy a GraphQL API With StepZen in Minutes StepZen, an IBM Cohttps://www.youtube.com/watch?v=CHJ9he5KlNs
  • https://stepzen.com/developers
  • **QUICKSTART https://stepzen.com/docs (readthedocs?)
• 63.3b #14b [5] documenting graphQL api spectraQL (ANVIL, https://github.com/anvilco/spectaql) DOCUMENT (NO YOUTUBE) https://www.useanvil.com/blog/engineering/autogenerate-graphql-docs-with-spectaql/

24.0919 Gdrive

Deploy API server (AWS, Gitbook, Heroku, etc etc).

• How to Deploy FastAPI on AWS EC2: Quick and Easy Steps! pixegami https://www.youtube.com/watch?v=SgSnz7kW-Ko
• Deploy FastAPI on AWS Lambda ⚡ Serverless hosting! pixegami https://www.youtube.com/watch?v=RGIM4JfsSk0

• https://django-rest-swagger.readthedocs.io/en/latest/
• https://www.django-rest-framework.org/
• https://www.geeksforgeeks.org/swagger-integration-with-python-django/
• https://www.youtube.com/watch?v=fbIFdWj8PsY Swagger API documentation with Django REST Framework Developer Timeline

• ***I built the same app 3 times | Which Python Framework is best? Django vs Flask vs FastAPI Patrick Loeber https://www.youtube.com/watch?v=3vfum74ggHE
• FastAPI, Flask or Django - Which Should You Use? Tech With Tim https://www.youtube.com/watch?v=cNlJCQHSmbE
• FastAPI vs. Django REST Framework: Which One Should You Choose? Eric Roby https://www.youtube.com/watch?v=bGw9An9rI18

https://github.com/anandrmedia/heroku-free-alternatives

• adaptable.io | Just connect your GitHub repository and let Adaptable handle the rest.
• alwaysdata.com | All your services in one place.
• argonaut.dev | Deploy apps and infrastructure on your cloud in minutes. Support for custom and third-party app deployments on Kubernetes and Lambda environments.
• cockroachlabs.cloud | Database - CockroachDB Serverless is a next-generation PostgreSQL, with consumption-based, truly elastic scaling and pricing. It has a free tier and no credit card is needed for signing up.
• cloud66.com | Cloud 66 gives you everything you need to build, deploy and grow your applications on any cloud, without the headache of the "server stuff"
• deta.sh | Build & deploy your ideas on the universe's most developer friendly cloud platform.
• dokku.com | An open source PAAS alternative to Heroku.
• domcloud.co | It's like those modern hosting platforms, but for the old school.
• koyeb.com | For deploying full stack apps and APIs globally. Enjoy high-end performance thanks to fully automated deployments to BareMetal servers and our built-in edge network.
• netlify.com | Free static site hosting with GitHub integration
• northflank.com | Deploy any code, job, or database in seconds.
• qoddi.com | Qoddi is a fully managed App Hosting Platform running on a tier 1 network at 10% of the cost of similar solutions.
• render.com | One of the top Heroku alternatives with a free plan to get started.
• withcoherence.com | Coherence automates DevOps for early stage teams laser focused on customer value.

• (1 ya) (GIT) What is Swagger | Swagger For Beginners | API documentation | How to use Swagger | Viswateja TejaWithData https://www.youtube.com/watch?v=xQfMARPNycI

• (1ya, NO GIT) Spring Boot Server Implementation Using OpenAPI Generator by Andriy Kucher Engineering Community https://www.youtube.com/watch?v=FJv5sGt3EEs
• (1ya, GIT, India) OpenAPI Generator Demo for Spring Boot | Generate Web & WebFlux Server Code | Swagger UI [Dev Problems] https://www.youtube.com/watch?v=GJOwJrqIV-8(https://www.youtube.com/@devproblems)

• 63.0_#28_1.1_DJANGO_DaveGray_v03_24.0814_0916.docx https://www.youtube.com/watch?v=Rp5vd34d-z4
  • for #1 create api try (google "add swagger to django rest framework")
    • https://django-rest-swagger.readthedocs.io/en/latest/
    • https://www.django-rest-framework.org/topics/documenting-your-api/
    • https://www.geeksforgeeks.org/swagger-integration-with-python-django/
    • Swagger API documentation with Django REST Framework Developer Timeline https://www.youtube.com/watch?v=fbIFdWj8PsY
• FLASK WEBSITE deployment page has good server info
  • https://flask.palletsprojects.com/en/3.0.x/quickstart/
  • https://flask.palletsprojects.com/en/3.0.x/tutorial/
  • **https://flask.palletsprojects.com/en/3.0.x/deploying/

• *docs.github.com/en/graphql/reference/queries

• nordicapis.com/how-to-autogenerate-graphql-api-documentation/

  • 1. SpectaQL
  • 2. Magidoc
  • 3. DociQL
  • 4. Graphql-docs
  • 5. GraphDoc
  • Learn The GraphQL Schema

• GraphQL schema itself can include a lot of documentation. You can add descriptions to every field

• github.com/magidoc-org/magidoc

• github.com/anvilco/spectaql

• developer.ibm.com/articles/awb-creating-static-documentation-graphql-apis-using-graphql/

  • https://register.saas.ibm.com/apic/trial/aws?cm_sp=ibmdev-_-developer-_-trial

• The Right Way To Build REST APIs Awesome https://www.youtube.com/watch?v=CVBpYfPKGlE

• (strange) Documentation of a Custom Python Package using Sphinx and Read the Docs | ubml | ‪@UBprogrammer‬ UBprogrammer https://www.youtube.com/watch?v=oHH40yXI2A8

• run api tests on R. Labbe python repo fork @ https://github.com/rlabbe/filterpy/tree/master. 20b_1_rlabbe_fork_api_v01_24.0831.docx

• for python / api + swagger + web

  • python
    • demos
      • xxhttps://www.geeksforgeeks.org/swagger-ui/#
      • https://www.geeksforgeeks.org/implement-a-python-rest-api-with-flask-flasgger/
      • https://swagger.io/blog/api-development/automatically-generating-swagger-specifications-wi/
    • FORK github.com/rlabbe/filterpy/tree/master docu
    • add stuff to create swagger
    • import swagger into
      • gitbook

• mozilla The WebSocket API (WebSockets) https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API
• amazon https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-overview.html
• tutorialspoint https://www.tutorialspoint.com/websockets/websockets_api.htm
• geeks https://www.geeksforgeeks.org/difference-between-rest-api-and-web-socket-api/#

My focus is on the the following

• Python
  • fastapi
  • flask
  • django. add swagger:
    • github.com/tfranzel/drf-spectacular
    • drf-yasg.readthedocs.io/en/stable/
    • appliku.com/post/django-rest-framework-swagger-openapi-tutorial/
• C#
  • Swashbuckle
  • NSwag
• Java (Spring)
• Swagger editor, Postman
• Deployment
• GraphQL

adaptable.io Just connect your GitHub repository and let Adaptable handle the rest. alwaysdata.com All your services in one place. argonaut.dev Deploy apps and infrastructure on your cloud in minutes. Support for custom and third-party app deployments on Kubernetes and Lambda environments. cockroachlabs.cloud Database - CockroachDB Serverless is a next-generation PostgreSQL, with consumption-based, truly elastic scaling and pricing. It has a free tier and no credit card is needed for signing up. cloud66.com Cloud 66 gives you everything you need to build, deploy and grow your applications on any cloud, without the headache of the "server stuff" deta.sh Build & deploy your ideas on the universe's most developer friendly cloud platform. dokku.com An open source PAAS alternative to Heroku. domcloud.co It's like those modern hosting platforms, but for the old school. koyeb.com For deploying full stack apps and APIs globally. Enjoy high-end performance thanks to fully automated deployments to BareMetal servers and our built-in edge network. netlify.com Free static site hosting with GitHub integration northflank.com Deploy any code, job, or database in seconds. qoddi.com Qoddi is a fully managed App Hosting Platform running on a tier 1 network at 10% of the cost of similar solutions. render.com One of the top Heroku alternatives with a free plan to get started. withcoherence.com Coherence automates DevOps for early stage teams laser focused on customer value.

24.0903

(gdrive) (no docs for this topics yet).

I created the core end user docs for almost all projects I have worked. The basic process that I have used (very successfully) is the following:

1 Initial tasks (~first month):

• Create an internal github wiki with access for all.
• Add any existing Quick Start, Getting Started docs (or similar docs).
• Perform hands-on exploration of the target product.
• Create (and publish internally) detailed and accurate (draft WIP) QS/GS docs.

2 Constantly build out the documentation:

• Reorg wiki constantly, adding commentary, corrections.
• After getting sufficient target product experience: Add more docs (User Guide, programming guide, API refs, etc).
• Note: Continue to use Wiki/docx until confident of content and organization for entire doc set.

3 Demo final release doc tools:

• Demo several options.
• Add some of the existing docs.

4 Create a draft WIP doc site:

• Select doc tools.
• Publish.
• Push for feedback from SME's.

5 Constant improvement.

24.0922 Gdrive

(google "add swagger to django rest framework")

• Django REST Swagger https://django-rest-swagger.readthedocs.io/en/latest/
• Django REST framework https://www.django-rest-framework.org/topics/documenting-your-api/
• Swagger Integration with Python Django https://www.geeksforgeeks.org/swagger-integration-with-python-django/
• Swagger API documentation with Django REST Framework Developer Timeline https://www.youtube.com/watch?v=fbIFdWj8PsY

• (OK) 63.7_#43_sdk_caleb_v02_24.0921.docx. Create a simple SDK.
• 63.5 #15 Build a .NET SDK with OpenAPI and NSwag .NET Conf 2022 (no git) 63.2_(1.4)_api_sdk_graphql_v06_23.0901_24.0903_SANITIZED.docx
• 63.5 #16 Writing a Python SDK (git) hedera smart contracts 63.2_(1.4)_api_sdk_graphql_v06_23.0901_24.0903_SANITIZED.docx
• 63.5 #22 rlabbe fork 24.0831 (THIS IS FOR CREATING OWN SDK OFF OF THIS) 63.9_(20b_1)api_rlabbe_fork(+swag+flask)_v02_24.0903.docx

• 63.7__63.2a.1#42_nswag_v07_24.0920.docx
• _63.7__63.2a.2 #6 3 How to Generate C# Http Client in NSwag Swagger codegen Swashbuckle Logan Dunning 63.1_api_swagger-gen_web-publish_v04_24.0908.docx
• 63.7__63.2a.2 #17 How To Use Nswag With ASP.NET Core And Generate Client Code With Nswag Studio 63.2(1.4)_api_sdk_graphql_v06_23.0901_24.0903_SANITIZED.docx

• 63.7__63.0 #18 TS digitalocean setting-up-a-node-project-with-typescript WORKS! 63.2(1.4)_api_sdk_graphql_v06_23.0901_24.0903_SANITIZED.docx

• 63.7__63.2a.1,2 #12 [1] microsoft (.NET + APIs + SwashbuckleNSwag) 63.2(1.4)_api_sdk_graphql_v06_23.0901_24.0903_SANITIZED.docx