What is REST?
The Workfront API conforms to a Representational State Transfer (REST) architecture standard. REST is a web development specification that was introduced to make web services easy to work with, consistent, fast, compatible, and scalable. While REST is a standard, there are certain allowances on how a program that conforms to REST architecture may be structured. Due to this flexibility, programs that conform to the REST standard are often referred to as RESTful.
There are six main constraints which are used to define the high-level characteristics of a RESTful API web service:
- Uniform Interface: Implies that every resource on a server must be accessible in the same way, regardless of how those resources are being accessed.
- Client-server: This implies an independence between you, the client, and the server from which you request information from. That is, you should be able to make changes to your program without having an impact on the structure of the API servers that your program makes requests to. Conversely, changes made to the API servers where resources are stored shouldn't affect you, the client, or your programs that depend on those resources.
- Stateless: When operations are stateless it means that a request contains all the information that is necessary for a server to fulfill that request. This implies that neither you or the server need to store any information in order to complete a request.
- Cacheable: Not all resources have to be cacheable, but if a resource is cacheable, it must make this known to you. Caching is important because it can help to reduce potential network stress.
- Layered system: Layered systems transmit and store data from multiple servers, but a client should never be aware of which servers are sending or receiving particular requests and responses.
- Code on demand (optional): Is an optional constraint which has largely been ignored over the years. A code on demand system can automatically generate code and send it to a client, which automatically accepts the code. This constraint remains controversial, mainly with regard to security concerns.
Why REST architecture?
One of the biggest benefits of working with a RESTful API is versatility. The simplicity imposed by REST gives you the option to work with the programming language(s) of your choice, so long as your program can make requests using the main operators specified by the Workfront API. Similarly, Workfront isn't forced to constrain its server structures to any particular standard, so long as the necessary servers can communicate with the Workfront API servers correctly.
Since nearly any language can be used on both sides of the API, there are many different possibilities for how examples could be handled in the Workfront API documentation. For the purposes of simplicity, all of the examples contained in the Workfront API Documentation are handled in JSON. Using JSON throughout API documentation is a generally accepted practice throughout the industry. Additionally, JSON is the format in which information will be returned to you by the Workfront API servers.
RESTful operations
While not a requirement of RESTful architecture, most RESTful APIs rely on Hyper Text Transfer Protocols (HTTP) to make requests and receive responses. HTTP limits the exchange of information between systems to these operations:
- GET
- HEAD
- POST
- PUT
- PATCH
- DELETE
- CONNECT
- OPTIONS
- TRACE
CRUD operations
It's a generally accepted practice to reduce RESTful API operations down to a spare number, regardless of which protocol you're using, based on the operations outlined in the CRUD acronym, which stands for:
- Create
- Read
- Update
- Delete
Workfront API operations
The Workfront API utilizes HTTP methods, but--as is the case with most RESTful APIs--primarily relies on a more limited set of operators, which align with the operations specified by the CRUD acronym:
- POST: Creates a new object
- GET: Reads information from Workfront Servers
- PUT: Updates an existing object
- DELETE: Deletes an Object