Getting Started

An API documentation example website

Why REST Services?

Representational State Transfer (REST) is an architectural style that is used for creating web services that transfers data between entities (Wikipedia definition).

Using our REST services, you can transfer user and guitar data from the Groovy Guitars database to your website server and use the data to display the Groovy Guitars collections. You can also can add your own guitars to our collections and display your guitars on other websites.

Authentication and Authorization

For security, licensing, and tracking purposes, you need to obtain an authentication token and create an account before using the REST APIs. Learn more about authentication and authorization

Note: You must have a paid subscription to access our guitar collections. For more information, contact us.

Header Characteristics

Our APIs use the following header characteristics:

  • Authorization: Contains the authentication information for the resource being requested. For more information, see Authentication and Authorization.
  • WWW-Authenticate: Sent by the server if a form of authentication is required) before it can respond with the actual resource being requested.
  • Accept-Charset: Indicates the  character sets that are accepted by Groovy Guitars.
  • Content-Type:  Indicates the media type (text/html or text/JSON) of the response sent to the client by the server, this will help the client in processing the response body correctly.
  • Cache-Control: Includes the cache policy defined by the server for this response, a cached response can be stored by the client and re-used till the time defined by the Cache-Control header.

Requests

Request “methods” include:

  • GET: Retrieves data from the database.
  • POST: Adds new information to the database.
  • PUT: Updates existing information in the database.
  • DELETE: Removes data from the database.

Make Request Call

To make a request, you can use can use cURL or Postman with the parameters defined in the endpoint documentation to send the request.

Example Request

The following is an example request using the PUT method:

curl -X PUT “http://groovyguitars.com/electric” -H “accept: **” -H “Content-Type: application/json” -d “{“id “:100,”manufacturer”:”Fender”,”model”:”Telecaster”,”condition”:”Good”,”price”:649.99,”color”:”black”,”numberstrings”:6,”material”:”Mahogany”}”

Responses

The response returns the data from the request service, which includes the guitar details. The data is formatted in either JSON or XML, as specified in the request. For more information, see the applicable endpoint documentation.

Code Examples

You can view examples of the code sent in the request and returned in the response.  For more information, see Code Samples.

Status and Error Codes

REST calls are either processed successfully or an error in the request code or a server issue may cause the call to fail. In either case, a “success” or “error” message is returned to inform the user of status of the request. For more information, see Status Codes.