<commit_before>---
date: '2016-09-29 20:56 +0200'
published: true
title: API Design
category:
  - dev
---
## Great API's
Years of experience of dealing with different kinds of APIs have left the developer community with a pretty good sense of the need-to-have features of any good API. 

* **Developer friendly:**
* **Extensibility:**
* **Up-to-date documentation:** 
* **Proper error handling:** 
* **Provides multiple SDK/libraries:** 
* **Security:** 
* **Scalability:** 

### Developer Friendly
By definition, an API is an application programming interface, with the key word being interface. When thinking about designing an API that will be used by developers other than yourself, the key aspect, Developer eXperience (or DX), needs to be taken into consideration.

Even when the API will be used by another system, the integration into that system is first done by one or more developers—human beings that bring the human factor into that integration. This means you’ll want the API to be as easy to use as possible, which makes for a great DX, and which should translate into more developers and client applications using the API.

Since simplifying things for humans could lead into an oversimplification of the interface, which in turn could lead to design issues when dealing with complex functionalities.
It is important to consider the DX as one of the major aspects of an API, but there are other aspects that have to be taken into consideration and have weight in the design decisions.

#### Communication’s Protocol
This is one of the most basic aspects of the interface. When choosing a communication protocol, it’s always a good idea to go with one that is familiar to the developers using the API. There are several standards that already have libraries and modules available in many programming languages (e.g., HTTP, FTP, SSH, etc.).

A custom-made protocol isn’t always a good idea because you’ll lose that instant portability in so many existing technologies. That said, if you’re ready to create support libraries for the most used languages, and your custom protocol is more efficient for your use case, it could be the right choice.

In the end, it’s up to the API designer to evaluate the best solution based on the context he’s working in.<commit_msg>Updated 2016-09-29-api-design.md<commit_after>---
date: '2016-09-29 20:56 +0200'
published: true
title: API Design
category:
  - dev
  - node
---
## Great API's
Years of experience of dealing with different kinds of APIs have left the developer community with a pretty good sense of the need-to-have features of any good API. 

* **Developer friendly:**
* **Extensibility:**
* **Up-to-date documentation:** 
* **Proper error handling:** 
* **Provides multiple SDK/libraries:** 
* **Security:** 
* **Scalability:** 

### Developer Friendly
By definition, an API is an application programming interface, with the key word being interface. When thinking about designing an API that will be used by developers other than yourself, the key aspect, Developer eXperience (or DX), needs to be taken into consideration.

Even when the API will be used by another system, the integration into that system is first done by one or more developers—human beings that bring the human factor into that integration. This means you’ll want the API to be as easy to use as possible, which makes for a great DX, and which should translate into more developers and client applications using the API.

Since simplifying things for humans could lead into an oversimplification of the interface, which in turn could lead to design issues when dealing with complex functionalities.
It is important to consider the DX as one of the major aspects of an API, but there are other aspects that have to be taken into consideration and have weight in the design decisions.

#### Communication’s Protocol
This is one of the most basic aspects of the interface. When choosing a communication protocol, it’s always a good idea to go with one that is familiar to the developers using the API. There are several standards that already have libraries and modules available in many programming languages (e.g., HTTP, FTP, SSH, etc.).

A custom-made protocol isn’t always a good idea because you’ll lose that instant portability in so many existing technologies. That said, if you’re ready to create support libraries for the most used languages, and your custom protocol is more efficient for your use case, it could be the right choice.

In the end, it’s up to the API designer to evaluate the best solution based on the context he’s working in.
{'fraction_non_alphanumeric': 0.05625817706061927, 'fraction_numerical': 0.00872219799389446, 'mean_word_length': 4.513221153846154, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6863841', 'n_tokens_mistral': 1111, 'n_tokens_neox': 1054, 'n_words': 707}