What exactly is an API endpoint

Just like the human bones connect with each other via the joint, likewise, an API connects two software, enabling them to interact and transfer data. API is an acronym for Application Programming Interface. To read more about API you should check here.

What exactly is an API endpoint?

Endpoints are the end path of a resource URL and usually have brief descriptions. Also, an endpoint shows how you can access specific information from a resource, not the base path shared by all endpoints.

API URL is not an Endpoint

This is a common mistake people make most times, identifying an endpoint as URL is wrong. URL is a base path to the resource API, it can be associated with any HTTP method.

An API URL Path is an address that allows you to access an API and its various features. It is the base address for a specific API that you’re using. Until you choose a specific Endpoint, though, the base URL isn’t going to do much.

Jsonplaceholder

A URL is the full address for the resource which has multiple parts i.e. base path and endpoint – Nauman Ali

API endpoint

The API full address isn’t going to do much for you without adding a base path and a specific endpoint. An endpoint is arguably the most critical aspect of API documentation because this is what developers will implement to make their requests.

Those specific characters to be added are URI; “a sequence of characters that identifies a web resource by location, name, or both available on the internet”. It is the added characters that make it unique from others in the same resource.

An endpoint contains detailed information; it could be about the weather forecast for a specific location or information about a user/anything with the use of HTTP methods and parameters, a response that contains elements about the endpoint is displayed.

https://api.openweathermap.org/com/surfreport/123?&days=2&units=metrics&hour=1400

Request from an API endpoint

Every API call returns expected information, in the case of our chosen API endpoint above, you’ll get the following surfreport element:

• Beach
• Day
• surfheight (units: feet)
• wind (units: kts)
• tide (units: feet)
• water temperature (units: F degrees)
• recommendation - string (“suggest something you could do with the information")

Sample code in getting the above information

{
    "surfreport": [
        {
            "beach": "Santa Cruz",
            "monday": {
                "1pm": {
                    "tide": 5,
                    "wind": 15,
                    "watertemp": 80,
                    "surfheight": 5,
                    "recommendation": "Go surfing!"
                },
                "2pm": {
                    "tide": -1,
                    "wind": 1,
                    "watertemp": 50,
                    "surfheight": 3,
                    "recommendation": "Surfing conditions are okay, not great."
                },
                "3pm": {
                    "tide": -1,
                    "wind": 10,
                    "watertemp": 65,
                    "surfheight": 1,
                    "recommendation": "Not a good day for surfing."
                }
                ...
            }
        }
    ]
}

If you have a lot of endpoints to document, you’ll probably want to create templates that follow a common structure - Tom Johnson

Expected error from an API endpoint

There are situations where you may make an API call expecting to see a JSON file but instead you are seeing an HTML error page,
causing you to think at what point did my code go wrong?

That’s the point you forgot to send an “Accept” header with your request. Cases like this are synonymous with Symfony; A PHP framework whose default error response is a 500 HTML error page.

Also, you may have seen a 404 status code with an error message in your browser response saying page not found?

This error simply means that your browser is able to communicate to the server where your API is being stored. Initiated a connection but the server could not find what you are looking for thus responding with a 404 error. There are many reasons like broken links, deleted or moved content, etc. That could lead to 404 pages.

As a technical writer documenting an API, you are faced with an error trying to test an API and you feel your heart beating so fast with fear of how you can handle such an error. An error like “Invalid Fields” are common during API test, data is returned in a manner that is incorrect and unexpected.

Solutions to this error are basically stated during the development of the API docs, making such all fields are described to increase consistency during API tests. Linking your page properly gives your browser the necessary information to display to site visitors and fix the 404 status code.

According to NordicAPI An API is only as good as its documentation
While documenting your API you test to see the response and describe each field according to its purpose. Documentation is key.

Conclusion

The understanding that an API endpoint is a base path with characters that makes it unique among others in the same resource is key, and to operate on an API endpoint totally depends on your HTTP method that is been specified in the documentation, be it “GET, POST, PUT or etc”.
“Forgetting a single "s" can get you in a lot of trouble when testing an API. Some APIs may only support HTTPS, while others may support HTTP for some endpoints and not others.”

Thanks for taking out the time to read this brief information about API endpoints.