Jamestown Distributors API v2.0 Documentation
Our API provides programmatic access to Jamestown Distributors, enabling anyone to write innovative applications and utilities on top of our rich database.
What can I do with the API?
Anything you want! The sky is the limit for awesome applications built using our database of guides. We can't wait to see what you come up with!
The API provides access to our guides (step-by-step guides and namespace pages), categories, users, teams, and our reputation badges.
The API responds with JSON by default, but you can also request XML (on some endpoints). For human-palatable formatted json, append ?pretty to the end of any request.
If you build on our API, we will support you by maintaining future compatibility. Make sure to version your API calls with 2.0. When we introduce changes that may break existing apps, we will increment the version number.
Getting Started
The best way to get started is to just dive right in! You don't need an app id for most requests, so you can start writing your app right now. Here's an example API call:
curl https://guides.jamestowndistributors.com/api/2.0/guides/20
Pretty simple! If you want to build an offline tool, an archived collection of oManual files is also available.
HTTP Request Methods
Where possible, we use appropriate HTTP verbs for each action. For a more detailed explanation, check out the full list of HTTP Request Methods.
- GET
- Retrieve a specific resource.
- POST
- Create a new resource.
- PATCH
- Update to a resource, only changing the provided attributes.
- PUT
- Replace a resource. If the resource doesn't exist, it is created.
- DELETE
- Delete a resource. This is also used in actions such as un-favoriting and un-completing a guide.
Client Errors
We use HTTP Status Codes to notify the client of any problems that occurred during the request. Each response includes a status code which will tell you if the request succeeded or failed and why.
If the request failed, you'll receive one of seven responses:
400 Bad Request— Invalid JSON in request body.401 Unauthorized— Authentication required.403 Forbidden— User has insufficient privileges to perform request on specified resource.404 Not Found— Resource does not exist.405 Method Not Allowed— Unsupported HTTP request method for endpoint.409 Conflict— Conflict during save of resource. This is caused by the providedrevisionidbeing different than the current version. The response body is the current version of the resource. See Revisionids.422 Unprocessable Entity— Unable to satisfy request due to semantic errors. This is typically caused by missing fields or fields that contain invalid data. Requirements for specific fields are specified for each endpoint. Often, the response body will contain more information about the failure.
Authentication
Authentication through the API is done using authentication tokens which can be retrieved from the Authentication endpoints.
Here is an example request using curl:
curl -H "Authorization: api 1234567890ABCDEF" \
-H "X-App-Id: FEDCBA9876543210" \
"https://guides.jamestowndistributors.com/api/2.0/user/guides"
Raw and Rendered Text
We use wiki syntax throughout our site to format content on wikis, guides, etc.
For fields that are rendered using wiki syntax, the response will include both *_raw and *_rendered fields.
*_rawfields contain the original wiki syntax used for editing wiki content.*_renderedfields contain HTML from the transformed wiki syntax used for displaying content to the client.
Revisionids
Since we allow any number of users to create and edit content simultaneously, a revisionid field is included in the response for all resources that are versioned using revisionids. A query parameter containing the current revisionid of the resource being edited is required for all requests modifying resources with revisionids. For example:
PATCH https://guides.jamestowndistributors.com/api/2.0/guides/123?revisionid=32242
If the provided revisionid does not match the current revisionid of the resource, the changes will not be accepted. This is to prevent edit conflicts that can occur when multiple users are editing the same resource. Edit requests return the current version of the resource and an appropriate status code to indicate success or failure.
Limit & Offset
Many endpoints respond to limit and offset query parameters to perform pagination. For example, these API calls return the first two pages of guides:
https://guides.jamestowndistributors.com/api/2.0/guides?limit=20&offset=0
https://guides.jamestowndistributors.com/api/2.0/guides?limit=20&offset=20
Cross Origin Resource Sharing
We support Cross Origin Resource Sharing (CORS) for AJAX requests based on the CORS W3C working draft.
Here is an example request written in jQuery:
$.ajax({
url: "https://guides.jamestowndistributors.com/api/2.0/guides"
}).done(function(response) {
console.log(response);
});