Home‎ > ‎

REST/Service Tips

  • Don't re-invent SQL
    Are you trying to create a general-purpose query interface for arbitrary databases? Maybe instead of slaving over the ultimate generic REST or SOAP interface, you should just let clients connect to the database directly. Services are meant for higher-level concepts than just CRUD on table rows

  • The spec is everything
    Resist the urge to add behaviors and resources to your service before documenting them in the spec first. From the developer's point of view, the spec is the service; it's not like the functional spec for your app, where forgetting to specify "cut-n-paste" as a feature isn't a big deal. If the service doesn't behave like the spec you will spend the rest of your time supporting "bug compatibility". Turn the spec into unit tests and set up a build-server to police every source-control check-in

  • Say everything at once
    Latency is the enemy, so you can't request and deliver piecemeal. If you support POST on your Customers resource then you need to let the client submit everything about the customer: name, address, phone, email, everything. The GET method needs to return the names and IDs of everybody (within search parameters, if given), and GET on an individual customer should return their full address-book record. Likewise, an Orders resource should let the client send the order header, line items and payment details in a single POST

  • One concern per service
    The Customers resource should be on a separate service from the Orders resource, and they should only know about each others resources via URLs or well-defined IDs. That's because CRM or address-booking is a different concern than order management, or inventory control, or human resources, or mapping, photo management, content management, scheduling and so-on. This is important for both scaling and maintenance

  • Store IDs, but deliver URIs
    REST is built upon web standards, so if the results of a query must include an ID number that refers to another resource, then it needs to be delivered in the form of a URI--no matter how you chose to store it in your back-end. If you can't count on knowing the location of a suitable server for a resource, then you can use URNs (Uniform Resource Names, used in combination with URN resolvers)

  • Do not support multiple hostname aliases
    Don't let "http://www.servicehost.com/" and "http://servicehost.com/" and "http://service.servicehost.com/" all be valid roots for your URIs--pick one and stick with it. URIs are identifiers for the resource, don't confuse them with URLs

  • Idempotency is not something you cure with Viagra
    GETting the same resource multiple times should not have any side effects. While the underlying resource--and therefore the results--may change between GETs, it should only be as the consequence of a PUT or POST

  • Set Last-Modified properly
    When your service returns a resource, make sure the Last-Modified timestamp is set correctly in the HTTP headers. This is crucial for when you need to scale the system by adding caching proxies