APIcast
APIcast copied to clipboard
Create a doc to help people get started on policy development
[provide a description of the issue] People have requested a few pointers to get them started on policy development, and som eresources they can use to accelerate their learning
Expected Result
I have gathered these links from people as a starting point, and categories where more resources would be appreciated:
Writing APIcast Policies
Learning LUA Focus on lua 5.1/5.2
Learning LUA: read https://www.lua.org/manual/5.1/ Which links to https://www.lua.org/pil/ Learning NGINX and OpenResty Lean about NGINX config, phases, and OpenResty lua API and what can and can't be done..
https://openresty.org/download/agentzh-nginx-tutorials-en.html
https://github.com/openresty/lua-nginx-module - the full doc on the openresty directives blog posts http://openresty.org/en/resources.html OpenResty Hello World http://openresty.org/en/getting-started.html APIcast Policy Framework Phases for writing apicast policies Order of Policies & Phases Writing tests
Hello,
I would be interested in contributing to this topic, either writing or proofreading !
PRs welcome Nicolas.... you can start with above (just notes gathered from Michal and others) and your own experience and get the ball rolling! Maybe @alanmoran and others can then contribute too! Thanks for the offer of help!
👍 for contributing. I took some notes of my journey a while back so will dig that out. Will be good to start fresh and document our path through each of the sections. A good idea might be actually to build a real-world policy as part of the policy and document as we go. I'll have a think about that 🤔
Thanks @alanmoran sounds like @nmasse-itix is willing to get the ball rolling with an initial PR< then maybe you can add to it?
Here is the plan I had in my mind :
1 : setup your development environment and hello world
- install required software
- build apicast
- configure apicast with a mocked backend or with the 3scale backend
- make sure it works
- create an hello world policy
- test it
2 : nginx phases, openresty apis
- what you can do in which phase
- where to get more information about OpenResty
- which APIs you can use from OpenResty and which one have been replaced by an equivalent in APIcast
- common use cases: making an HTTP request, forwarding a request to a backend
3 : Policy design rules
- using the context
- configuration: how to specify the configuration of your policy
4 : Unit testing
- how to use the unit testing framework of Apicast
5 : Packaging your policy
- using external libraries
- building the final Docker image
What do you think ? @alanmoran do you see additional topics you would like to cover ?
Since it's quite a large amount of work, I planned to make a PR per chapter so that we don't have to wait too long for having something.
Hi Nicolas, that sounds like a good HOWTO...
the origin o fall of this was more a "things I need to learn first, and where to find resources to help me learn it"
so you might want to consider a section for that also (without scaring people off! :-) )
Yes, sure ! 😁
I think "Integration testing" is necessary after "Unit testing".
And we should do the schema testing using ajv
if possible, because s2i-builder
checks the schema and sometimes we cannot find the schema errors in the unit testing or the integration testing.
I would also like to be involved, by reviewing/proofreading or testing out the documentation. Been doing a lot of learning lately in the Openresty area, still an ongoing journey for me. But this sounds like a good place to get some participation in.