As we have discussed in the earlier chapter, API developers are the raison d'être of APIs. Helping them find the right APIs and helping them figure out programmatically whether the site that's being accessed has an API enabled or not will be the most critical responsibility of the API.

The primary step to connect with a site is to find out if the site is API enabled by simple URLs that are be using as user input to help us verify the API's availability. They also help us find out how to access them.

Discoverability of the API is all about the descriptive capability of the server to instruct the client on the usage of the API.

Let's look at the two types of discoverability in the following section and their implementation in our code examples (as screenshots):

1. By valid HTTP methods: When clients call REST services with invalid HTTP methods, the response of that request should end up in the 405 HTTP error code; that is, 405 Method Not Allowed. In addition to the error code, the response header should provide flexibility to the client to find the supported methods that allow headers in its response. The code for this is as follows:

@DeleteMapping("/investors/{investorId}/stocks/{symbol}") 
public ResponseEntity<Void> deleteAStockFromTheInvestorPortfolio( 
  @PathVariable String investor, 
  @PathVariable String symbol) { 
    if (investorService.deleteStockFromTheInvestorPortfolio(investorId, symbol)) { 
      return ResponseEntity.noContent().build(); 
    } 
    return ResponseEntity.ok(null); 
} 

The output of the preceding code is as follows:

2. By providing the URI of the newly created resource: Including the URI as part of the location header as the response to the newly created resource is another method of discoverability. The returned URI as a location will be available through GET. The code for it is as follows:

@PostMapping("/investors/{investorId}/stocks") 
public ResponseEntity<Void......) { 
  Stock insertedStock = investorService.addNewSto...; 
  if (insertedStock == null) { 
    return ResponseEntity.noContent().build(); 
  } 
  URI location = ServletUriComponentsBuilder..... 
  return ResponseEntity.created(location).build(); 
} 

The output for the preceding code is as follows:

Please note that, as our examples are using spring boot, we are leveraging the capabilities of spring boot's seamless and out-of-the-box implementations for discoverability (with @GetMapping, the servlets URI components builder, and so on).

One more type of discoverability (yet to be standardized, though) can be implemented through valid link headers. While responding to the client's particular resources through GET, you must provide the client with clues about what they can do next as well; that is, providing a list of all available resources as a list through the link header:

As a live example of discoverability, the preceding screenshot depicts one of Google's APIs.