This project is a partial implementation of a Leprechaun social network. It is purely designed as jumping off point for discussions on a few opinionated best practices in API design and a practical application of those practices.
- Version your API
- Always use SSL (Leprechauns are very secretive)
- Auth tokens can offload some server load
- Use HTTP methods appropriately
- Keep your resource URLs simple
- Make relationships nested segments
- Move advanced* use cases into query strings
- Add shortcut routes for common queries
- Be declarative in defining model properties, ACL, validations and relationships
- Document your API
- Use cache headers for clients
- Use server cache
- Provide consumable error responses
- Write tests for failures & successes
*embedding, sorting, filtering, field limiting, pagination
git clone https://github.com/MikeCostello/api-demo.git
cd api-demo
npm install
To launch the API server run:
npm start
Documentation is a good place to start https://localhost:3000/explorer and is generated by swagger
The HTTPS server uses a self signed certificate. While CA and domain mismatch warnings can safely be ignored, installing the cert locally will clear them up. Installing Self-signed Certificates
The generated documentation itself can be used directly to explore the API, alternatively a collection of Postman calls can be imported. The first call should always be to Clients/login to retrieve an auth token.
To run unit tests:
npm test