API Introduction
Publisher: Psychz Networks, March 20,2023Intro
APIs (Application Programming Interface) are a fundamental part of modern software development, allowing software components to interact and providing developers with a standard and efficient way to build applications that can easily integrate with other software systems. APIs can be used in various ways, but they are most commonly used to enable communication between a client and a server or between different software components within the same application.
APIs can be classified into different types based on their functionality and architecture, such as web APIs, REST APIs, SOAP APIs, and many others.
With the help of Psychz APIs, you can integrate your system to perform seamless processing of various services on your servers. You can view the entire list of available APIs and related information here https://www.psychz.net/api/doc/dist/
Requests
In an API request, one application (the client) sends a request to another application (the server) using a predefined set of rules and protocols. The server then processes the request and returns a response to the client, including data, status updates, or error messages. API requests can be used for various purposes, such as retrieving data from a database, sending messages between applications, or integrating different software systems.
GET
An API GET request is an HTTP request that commonly retrieves data from a web server or API. When you make a GET request, you ask the server to return a specific resource or data associated with a URL. To make a GET request, you typically use an HTTP client library or tool, such as cURL, Postman, or the Python requests library. The client requests the server with the desired resource's URL and any additional parameters the API requires.
For example, you can use Psychz API to find the status of your OS installation request. The status allows you to check the progress of your OS installation in real time. The completion status is shown in %. The request URL for this might look something like this:
The server would respond with a JSON document containing the progress status of OS installation
{
"status": true,
"data": {
"status": "ready",
"progress": "100%"
}
}
weather data for that location. You can then use this data in your application to display the weather information to the user.
Important: When making API GET requests remember that they are generally read-only operations. In other words, you only retrieve data from the server, not making any changes. If you need to modify data on the server, you would typically use a different HTTP method, such as POST or PUT.
DELETE
DELETE requests are commonly used in web applications and APIs to remove data or records that are no longer needed or have become outdated. DELETE requests are typically used to delete a resource identified by a unique URL or URI (Uniform Resource Identifier). To make a DELETE request, the client sends an HTTP DELETE method to the server, along with the URL of the resource to be deleted. If the server receives the request and determines that the resource exists and can be deleted, it will delete the resource and send a response indicating success. If the server cannot delete the resource, it will send an error message with the appropriate status code.
PUT
PUT requests are commonly used in web applications and APIs to modify or update data stored on a server. To make a PUT request, the client sends an HTTP PUT method to the server, along with the resource URL to be updated and the new data to be stored in place of the old data.
POST
The POST method sends data to the server and creates a new resource. The resource it creates is subordinate to some other parent resource. When a new resource is POSTed to the parent, the API service will automatically associate the new resource by assigning it an ID (new resource URI). In short, this method is used to create a new data entry.
HTTP Statuses
HTTP status codes are essential for diagnosing and troubleshooting issues with web applications and APIs. By examining the status code returned by a server, developers can gain insight into what went wrong and take appropriate action to resolve the issue. These codes are three-digit numbers that indicate the status of a request made by a client to a server. There are five classes of status codes, each with its range of codes:
2xx Success: These codes indicate that the request was successful and the server has completed the requested action.
Examples: 200 - OK, 201 - Created, 204 - No Content.
4xx Client Errors: These codes indicate an error with the client's request.
Examples: 400 - Bad Request, 401 - Unauthorized, 404 - Not Found, 403 - Forbidden.
5xx Server Errors: These codes indicate an error on the server side while processing the request.
Examples: 500 - Internal Server Error, 502 - Bad Gateway, 503 - Service Unavailable.
ERROR RESPONSES
HTTP (Hypertext Transfer Protocol) status codes in the 4xx and 5xx range indicate errors in the client's request or the server's response. These error responses are intended to provide information about the error and help the client understand what went wrong. Here are some common HTTP error responses and their meanings:
400 Bad Request: The server cannot understand the client's request due to invalid syntax.
401 Unauthorized: The client must authenticate to get the requested response.
403 Forbidden: The client does not have access rights to the content or resource.
404 Not Found: The server cannot find the requested resource.
405 Method Not Allowed: The method used in the request is not allowed for the resource.
406 Not Acceptable: The server cannot produce a response matching the list of acceptable values defined in the request's headers.
500 Internal Server Error: The server encountered an unexpected condition that prevented it from fulfilling the request.
502 Bad Gateway: The server, acting as a gateway or proxy, received an invalid response from an upstream server it accessed to fulfill the request.
503 Service Unavailable: The server cannot handle the request due to maintenance, overloading, or other temporary reasons.
Pagination
API (Application Programming Interface) pagination is a technique that breaks down large data sets into smaller, more manageable chunks or pages. This is often necessary when working with APIs that return many results, such as search results or database queries, to avoid overwhelming the client or server with too much data at once.
API pagination typically involves two main parameters:
PAGE NUMBER
This parameter specifies which page of results the client wants to retrieve. For example, if the client wants to retrieve the second results page, they would set the page number to 2.
PAGE SIZE
This parameter specifies the number of results to include on each page. For example, if the client wants each page to have ten effects, they would set the page size to 10.
The API will then return the requested results page based on the specified page number and size.
Responses
The following are few examples of API responses
GET response code 200: To get a list of OS categories, OS partitions, etc
Request URL: https://api.psychz.net/v1/devices_detailed_list?access_token=xxx&access_username=yyy
{
"status": true,
"code" : 200,
"data": {
"123": {
"device_id": "123",
"client_id": "123",
"service_id": "001",
"device_name": "abc",
"label": "",
"category": "XYZ"
},
"134": {
"device_id": "134",
"client_id": "123",
"service_id": "002",
"device_name": "abc",
"label": "",
"category": "XYZ"
}
}
}
GET response code 200: List the client orders
Request URL: https://api.psychz.net/v1/order_list?access_token=xxx&access_username=yyy
{
"status": true,
"data": [
{
"order_id": "818524",
"total": "59.00",
"order_time": "2023-04-04 07:04",
"last_activity": "2023-04-04 07:04",
"service_category_code": "DEDICATED",
"plan_id": "441",
"title": "Promo: 100TB - Amsterdam :: E3-1270 v5",
"status": "Provisioned"
},
{
"order_id": "818516",
"total": "29.00",
"order_time": "2023-04-04 06:04",
"last_activity": "2023-04-04 06:04",
"service_category_code": "DEDICATED",
"plan_id": "389",
"title": "Promo: 1Gbps Unmetered - Los Angeles :: E3-1230 v2",
"status": "Provisioned"
},
{
"order_id": "818515",
"total": "316.00",
"order_time": "2023-04-04 05:04",
"last_activity": "2023-04-04 05:04",
"service_category_code": "DEDICATED",
"plan_id": "275",
"title": "Ashburn :: E3-1270 v5",
"status": "Provisioned"
}
........................................
........................................
]
}
GET response code 200: For Pagination request
Request URL: https://api.psychz.net/v1/devices_detailed_list?access_token=xxx&access_username=yyy&limit=5&offset=3
In this example, the API is returning a page of 5 items starting from the 4th item (offset=3). The limit parameter is set to 5, which means the response will include a maximum of 5 items.
{
"status": true,
"data": {
"6685": {
"device_id": "6685",
"client_id": "7155",
"service_id": "148118",
"device_name": "testdevice",
"label": "E3-1230 v2",
"category": "Dedicated Servers"
},
"9170": {
"device_id": "9170",
"client_id": "7155",
"service_id": "148113",
"device_name": "demotest",
"label": "E5-1650 v3 - Staging Server",
"category": "Dedicated Servers"
},
"9794": {
"device_id": "9794",
"client_id": "7155",
"service_id": "148114",
"device_name": "dv1",
"label": "E3-1270 v5",
"category": "Dedicated Servers"
},
"10102": {
"device_id": "10102",
"client_id": "7155",
"service_id": "147831",
"device_name": "Apparao-2",
"label": "E3-1230 v5",
"category": "Dedicated Servers"
},
"11064": {
"device_id": "11064",
"client_id": "7155",
"service_id": "143112",
"device_name": "psychzbizcdn",
"label": "",
"category": "Global Content Delivery Network"
}
}
}