What Are the Best Practices in Writing Restful Apis to Return Content?

What are the best practices in writing RESTful APIs to return content that contains both HTML and PDF content?

API ----- An API is an Application-Programmer Interface; essentially a set of functions, objects, and methods that are made publicly known to developers that allow them to interact with a particular technology. APIs are useful because t enable programmers to utilize the capabilities of different technologies without needing to know their internal implementation. Example. You can use the Mandrill API to enable whatever application you're writing to send emails with rich content. As a programmer, you don't need to know anything about how Mailchimp wrote Mandrill or how it works under the hood. With the API Mandrill provides (set of methods, functions, etc.) you can utilize its capabilities anyway. RESTful ----------- REST stands for Representational State Transfer. It is essentially an "architecture for networked applications." In other words, it's a set of standards that describe how computers should communicate with each other and with applications across a network. REST defines certain specific operations that applications should be able to do in order to satisfy all of the CRUD (create, read, update, delete) requirements. HTTP is the protocol most frequently used to implement the REST architecture, supplying operations like PUT, POST, GET, DELETE, and HEAD. RESTful APIs ------------------ Combining the two definitions, we now know that a RESTful API is an Application-Programmer Interface for communicating with an application across a network. For example. you as a web application programmer want to use a particular back-end service I wrote that does something useful. For instance, it returns a list of fruit with a particular property. I will define certain methods and routes you can call in order to use my service. You don't need to know how my service works under the hood, you just know certain things like. - what type of request do you need to send to my service. GET, POST, PUT, DELETE, HEAD? - where do you send the request (route?) - what data will this request/route return, and in what format? JSON? XML? What properties are defined? Example ------------ This is an example API for a few methods for my service. GET /api/fruit returns. A list of all fruit in JSON in alphabetical order { "fruit". [ "Apple", "Banana", "Crandberry", ... ] } GET /api/fruit?color="" returns. a list of fruit of the given color { "fruit". [ "Tomato", "Strawberry", "Raspberry" ] } POST /api/fruit accepts. an object defining a fruit. { "name". , "color". } returns. STATUS 200 OK on success, or some other applicable HTTP status code The above example an over-simplified version of what you might see looking at a RESTful API for some back-end service. Of course, real service APIs will have a lot more detail and documentation, but this is the gist. There are several other principles the REST architecture defines like the need for the service to be stateless, or cache-able, but my response goes over the most relevant information for typical day-to-day use.