A re-realization of the popular Django REST framework - Tasypie for Node.js and Hapi.js. Looking for active contributors / collaborators to help shape the way people build APIs!
API Documentation Working Example
Officially Supported Resources Types
Experimental Resource Types
Create a simple Api
const Resource Api = Api = tastypieApi hapi = server = v1 = 'api/v1' ; Resource = tastypieResource v1; server; server;
Self Describing
Tastypie exposes endpoint to descibe available resources and the contracts they expose
Resource listing
// GET /api/v1 "test": "schema": "/api/v1/test/schema" "detail": "/api/v1/test/{pk}" "list": "/api/v1/test"
Auto Schema
// GET /api/v1/test/schema "filtering": {} "ordering": "formats": "application/json" "text/javascript" "text/xml" "limit": 25 "fields": "lastName": "default": null "type": "string" "nullable": false "blank": false "readonly": false "help": "last name of the user" "unique": false "enum": "firstName": "default": null "type": "string" "nullable": false "blank": false "readonly": false "help": "first name of the user" "unique": false "enum": "id": "default": null "type": "string" "nullable": false "blank": false "readonly": true "help": "Unique identifier of this resource" "unique": false "enum": "uri": "default": null "type": "string" "nullable": false "blank": false "readonly": true "help": "The URI pointing back the this resource instance" "unique": false "enum": "allowed": "schema": "get" "detail": "get" "put" "post" "delete" "patch" "head" "options" "list": "get" "put" "post" "delete" "patch" "head" "options"
Get Data
// GET /api/v1/test "meta": "count":1 "limit":25 "next":null "previous":null "data": firstName:"Bill" lastName:"Bucks" uri:"/api/v1/test/1" // GET /api/v1/test/1 firstName:"Bill" lastName:"Bucks" uri:"/api/v1/test/1"
Built-in Fields
- field ( ApiField ) - Generic noop field - returns the data as it is given
- object ( ObjectField ) - Generic no-op field - returns the data as it is given
- char ( character / CharField ) - Converts values to strings
- array ( ArrayField ) Converts comma sparated strings into arrays
- int ( int / IntegerField ) converts numeric values into integers using
parseInt
- float ( FloatField ) Converts values to floating point number using
parseFloat
- bool ( BooleanField ) Forces values to booleans
- date ( DateField ) Converts date strings to Date objects with out any time data
- datetime ( DateTimeField ) Attempts to convert date time strings into date objects
- file ( FileField ) A field that pipes a stream to a configured location, and store a path
- filepath ( FilePathField ) A field that handles file locations rather than dealing with streams or binary data
This allows for full HTTP support and basic CRUD operations on a single enpoint - api/v1/test
curl -XPOST -H "Content-Type: applciation/json" -d '{"test":"fake"}' http://localhost:3000/api/v1/testcurl -XPUT -H "Content-Type: applciation/json" -d '{"test":"real"}' http://localhost:3000/api/v1/testcurl -XDELETE http://localhost:3000/api/v1/test/fake
HTTP Verbs
This is how tastypie handles the base HTTP Methods
- GET returns a list of resource instance or a specific resource instance
- DELETE removes a specific resource instance
- PUT REPLACES a resource instance. This is not a partial update. Any optional fields not defined will be set to undefined
- PATCH a PARTIAL update to a specific resource instance. Only the fields sent in the payload are dealt with.
- OPTIONS returns an empty response with the Allow header set
- HEAD, TRACE, and CONNECT are left to implementation on a per resource bases
Serialization
The base serializer can deal with xml
, json
and jsonp
out of the box. Serialization method is determined by the Accept
header or a format
query string param
curl -H "Accept: text/xml" http://localhost:3000/api/v1/testcurl http://localhost:3000/api/v1/test?format=xml
bill Schaefer
NOTE: hapi captures application/foo so for custom serialization, we must use text/foo
Quick & Dirty Resource
A functional resource, by convention, should define method handlers for each of the actions
( list
, detail
, schema
, etc ) & HTTP verbs
where it makes sense - where the resource method name is <VERB>_<ACTION>
.
const tastypie = const Resource = tastypieResource;const http = tasypiehttpconst Simple; const Template = { thiskey = null this_id = null} Templateprototype{ } Templateprototype{ return key _id} Simple = Resource;
Example FS resourse
The base resource defines many of the required <VERB>_<ACTION>
methods for you and delegates to smaller internal methods which you can over-ride to customize behaviors. Here is a resource that will asyncronously read a JSON file from disk are respond to GET requests. Supports XML, JSON, paging and dummy cache out of the box.
const hapi = ;const fs = const path = const Resource Api Fields Class Serializer = const Options = ClassOptions const debug = 'tastypie:example' const server = // make a simple object template to be populated during the hydration process// This could be an ORM Model class just as easily{ thisname = first: undefined last: undefined thisage = undefined; thisguid = undefined; thisrange = thiseyeColor = undefined;}; let Base = Resource;var api = 'api/v1' serializer: app; api; app;
Now you can read data from a file with your rest API
curl http://localhost:2000/api/v1/testcurl http://localhost:2000/api/v1/test?format=xmlcurl http://localhost:2000/api/v1/test/1curl http://localhost:2000/api/v1/test/2curl http://localhost:2000/api/v1/test/2?format=xml
Contributing
Contributions & patches welcome. If you have experience working with the original python / django-tastypie, input would be greatly appreciated. Anything from docs, test and feature code is fair game.
- Fork
- Write Code
- Write tests
- Document your code
- Push
- Open Pull Request