README is outdated.
Opened this issue · 3 comments
Reason
I'm a newbie and I encountered some issues while I'm following the README. The reason is the outdated API.
What I see
Some APIs are outdated, for example:
app.use(restify.queryParser());
app.use(restify.bodyParser());should be
app.use(restify.plugins.queryParser());
app.use(restify.plugins.bodyParser());And importing http module is unnecessary to launch an express app now.
We aim to be compatible with older versions of restify and express so they might be outdated but only with newer versions. In general the docs are meant to be guides in how to use finale and not how to create an express server. If there is something seriously out of date and the tests themselves are more up-to-date, please submit a pull request of both tests and docs. Thanks!
We aim to be compatible with older versions of restify and express so they might be outdated but only with newer versions.
You aim to have docs compatible with older versions of restify without specifying what those versions of restify are? How often are users coming across finale and actually following the README instructions regarding using restify, and are using older versions of restify, vs the more likely scenario of users adding restify package to their project and getting a newer version.
These changes(4.x to 5.x migration guide) happened with the v5 release back in mid 2017 with prior versions being 2016 and earlier.
It's an odd choice to prioritize documentation under compatibility reasons when the users most likely to benefit from the examples are those creating new projects which by default add the newer versions of restify. At the very least, make it clear on the README that you're showing an outdated v4.x restify integration example, and then link to this issue if you don't want to include the more common experience, since most will run into the problem when choosing to go with restify.
In general the docs are meant to be guides in how to use finale and not how to create an express server.
finale makes it easy to provide a REST API, it's ease-of-use oriented. You provide a quick example of how to get it working with mixed support/choice of express or restify shown. You're right that your docs aren't meant to be a guide to how to setup express or restify, but users that aren't familiar with either and just want to get the REST API service going may want to just go with your example and then sort out proper server setup after evaluating finale actually working for them.
Optionally drop the example of restify, but updating the docs to give a proper restify setup would be better. It wasn't immediately clear why/when the restify API changed, I hadn't used restify before myself, but had heard of it being good/appropriate for serving a REST service.
Please submit a pull request to the documentation and Ill merge it in if it's a better example