Think as UX: OpenSooq Designing APIs

The user experience (UX) is what a user of a particular product experiences when using that product. A UX designer’s job is thus to create a product that provides the best possible user experience.Designers spend a decent amount of time to make sure that they make every interaction, every UI element as delightful as possible.
Reflecting this on The APIs, designing APIs using concepts and processes which are used to design beautiful User Experiences, make these API’s easier to used by the end client’s and it provides great experience to them.

Design is not just what it looks like and feels like. Design is how it works.

— Steve Jobs.

On opensooq The API UX is mainly processes -the processes that we use to make sure that our API design is valuable , desirable and usable to the API Clients.
It is not just about providing a data , We make sure that in the design process all stakeholders are involved so that there are no sudden surprises towards the end.
We also do enough research, testing and prototyping to make sure that all the ideas we are generating, those resonate with the target API clients.
onate with the target API clients.

. . .

Opensooq API Life Cycle

API life cycle in opensooq contains a set of stages like
Designing, Debugging, Automated testing, Documenting the API, Monitoring and Publishing the API so the end clients can start consuming it.
So the Designing step is the first and most important step in API life cycle,
giving this step enough time , it will avoid us to building the wrong API , or
API in the wrong way , also changes made to the API in this stage are easy and cheap to perform.

. . .

Design an API with a great UX

To make sure all our APIs that we design follows a consistent pattern, and when new people joining our team do not reinvent the wheel of making design decisions about API, we have a process of API design similar to the one UX designers employ.
In order to design an API with a great UX, we follow the usability rules defined by Peter Morville known as UX Honeycomb which is rules for UX

The UX Honeycomb

Let’s talk about the above rules from opensooq point of view

1. Useful: Every opensooq API created for a specific purpose , to make it useful for the end clients.
Like listing API, the purpose of it return list of posts.

2. Usable: We make sure that our APIs are easy to use , we don’t but a lot of attributes to start using its functionality.
On listing API end client can start using it without any parameters , or they could send simple parameters to get more specification response.

3. Desirable: We Make sure the API functionality return what the end client expects.
For example on listing API the end client expect list of posts with title and description and image and price.

4. Findable: API documentation is very important , and this documentation can be found easily, and can developers start using it immediately.
For this purpose we use Swagger for documentation, and any opensooq developer can access it, to see any API documentation, and to try the API , and see what is the response shape

5. Accessible:Our APIs depends on authentication level to provide it’s functionality for end client who have technical constraints/limitations in consuming it.

6. Credible: In our case the API data hundred percent trusted by the end clients.
When the client expect specific values on response data, we make sure the API will return response in required values and the API can handle edge cases.

7. Valuable: Does the API contribute to the company bottom line and improve customer satisfaction?
With more than 2 billion request on the month , every new API will cost us more hits on the servers to handle the request and return the response, so we make sure the new API can really make a difference for the end clients and it will improve customers experience when start using the application , which effect directly on the company KPI’s.

. . .

APIs Design Proces

A design process helps us to remain transparent and efficient while designing a solution. It sets a clear expectation and decreases the risk of delivering unwanted results.
Here we follow The Double Diamond design process defined by the British Design Council is one of such many design processes. It allows us to make intentional design decisions by exploring various options (divergent thinking) while validating stronger ones and weeding out the weaker ones (convergent thinking).

The Double Diamond design process


When we are building a new API we are trying to solve a problem In order to provide a solution.
First thing we are trying to understand the problem, Then we Acquiring the Domain knowledge about the problem, Clarify on the use-cases and the requirement,
Also we Research on existing solutions to understand how they are solving the same problem and what we can learn from their architectural/technical decisions.

Also we make a meetings with all the teams inside our organization that are stakeholders for this new API which might include Product Team, Design Team, Client Team, etc, From all these perspective we make a broader view to think about our API and the technical decisions that we are planning to take from that point onward

This step will result in a lot of unstructured information, overlapping and conflicting use-cases/requirements. So the next step, will help us to structure this information so that we can make better design decisions around our API

Image result for Discover/Research images


We called this step also (collecting step), from the previous step result , We try to pin down exact use-cases and requirements we are planning to cater. Also in this step we define the API dependencies or another third party services , defending resource Models and relationships between them, also we clearly outline the behavior and expectations of the API so that consumers don’t have to make any assumptions while using your APIs.
Doing this will help us identify the amount of business logic that will be part of the API.


Once we are clear on ‘what needs to be achieved’ using APIs, it’s time to design the API so that we can communicate on what we as API provider intent to ship. t’s time to create API documentation and stats/scenarios, prototype.

API Documentation: In this phase we use Swagger for documenting headers, query parameters, etc in the request

Image result for swagger icons

Different API scenarios/states:Here we design different examples for every possible API scenario , so that end clients knows what request to send and what response to expect,including error responses, empty responses, etc.

Prototype:We create a Mock server that will return the designed examples as a response. This will enable our end clients to start prototyping /testing their use cases even through the actual API is not ready.

Deliver/Implementation: Here we start API implementation. But before we start coding , we create Contract Test for the API which will ensure that if anything changes during development in the agreed API request/response design, these contract tests will start failing. Then we can either update our code or inform all the affected teams about the new changes.
In our case we using Codeception in Yii framework , to create a test suite for our API.

Image result for codeception

Let’s take an example about API test suite
Test process: (Test Request) -> (Validate Response Using Json Schema) -> (Validate Database)


class RegistrationSchema
    public static function registrationApi()
    return <<<'JSON'
       "title": "Registration",
       "type": "object",
       "properties": {
           "success": {"type":"boolean", "enum":[true]},
           "result": {
               "type": "object",
               "status": {"type":"boolean", "enum":[true]},
               "data" : {
                   "type": "object",

Test Class:

class CreateUserCest
    public function testRegister(\ApiTester $I)
    $I->tester->wantTo("Register User");
    // test request
        $I->haveHttpHeader('Content-Type', 'application/x-www-form-urlencoded');
        $I->sendPOST('/users', [
          'name' => 'Miles',
          'email' => '',
      'password' => 123456

    // validate response
    $response = $I->grabResponse();
    $registrationSchema = RegistrationSchema::registrationApi();
    $response_validation = JsonResponseValidator::validateResponse($registrationSchema,$response);

    // validate database
        $userId = $response['result']['data']['id'];
   $I->seeInDatabase($tableName, ['id' => $userId]);

. . .

Our API Design Style Guid

When you are working in a growing team with new people joining in every now and then, after a certain point of time it becomes very difficult to ensure the quality, consistency, and security of the APIs. Imagine what would happen if every new developer will start following their own convention of naming endpoints, using Authorization, headers query parameters, success and error response structure, etc while developing an API.

We solve this by building Design Style Guides which make sure that everyone in the team uses the same URL Structure, Request methods, Request/Response Headers, etc. Using Design Style Guide it becomes easy to communicate between teams, keep APIs consistent in the long term and bring agility in the design and development processes.

  • URL Structure: As I mention Above we use Yii framework in the development , and it’s provide to us Standard url structure for the API.
  • Request methods: We Define a list of request method and when to use it. This will make sure that request methods have the same behavior across all our APIs.
Like : (POST) request method => whenever we use Post request method ,we are talking about add new data.
  • Request/Response Headers:
  • We using a list of headers with the API while requesting to service and responding back.
  • Response status codes: We have a list of allowed status codes for our API and we clearly set the guidelines on when to use a specific status code.
As an example (401) used when the authentication key is invalid.
  • Errors:
  • We create a standard error response format that all other developers can use.
As an example => user age validation error:
 "errors": [
      "field" : "age",
      "message": "Expected Integer value, string given."
  • Versioning:Here we have some instructions to keep in mind while we versioning and API.
As an example :
The new version must be optimized more than previous version.
The new version must be return something different about the previous one like (new type of data or new response format).
  • Filtering/Pagination/Sorting:We define a standard attributes for pagination and sorting , we agreed with other teams on it, but for filtering , it’s depends on the API and the response from it.

. . .


The API design process like any other design, needs to be an iterative process. Publishing an API to our end clients is not the end of an API lifecycle. We keep the channel of constant feedback from our API consumers, we always keep accommodating suggestions using the same design process.

Software Technologist

Leave a reply:

Your email address will not be published.

Site Footer

@ OpenSooq 2019