This survey is meant to explore good and bad practices adopted by software ... How many years have you been employed in
Good and Bad Practices in Designing Stable Web APIs Introduction to the survey
Thanks for taking time in participating in this survey! This survey is meant to explore good and bad practices adopted by software developers/designers/engineers while designing stable web APIs. In the next minutes you will be asked to share your expertise and experience in evaluating design practices and how they can affect the stability of a web API. Before continuing please agree with the following terminology: Web API: a specification of how a software component distributed over a network can be invoked. It includes the operations that can be invoked and the data structures that specify the input and output messages of the operations. WSDL and RESTful APIs are examples of web APIs. Quality attributes: are attributes that describe the system’s intended behavior within the environment for which it was built. Examples of quality attributes for assessing the quality of a web API are usability, performance, stability, security, scalability, understandability etc. The most common quality attributes will be described along the survey. This survey is composed of two parts. In the first part you will be asked about your background information. In the second part, you will be asked to express your thoughts about how 5 design practices can affect the stability of a web API. This survey will take approximately 20 minutes. Yet the time strongly depends on how passionate you will get while reasoning about the design practices. Don't forget to fill in your email address on the last page of the survey to win one of the five 20€ Amazon vouchers! ;;) Thanks in advance for your willingness in participating in this survey and...have fun! Daniele Romano, MSc PhD Candidate ---------------------------------------------------------- Software Engineering Research Group Delft University of Technology The Netherlands
Page 1
Good and Bad Practices in Designing Stable Web APIs Background
Let's start...introduce yourself!
*1. I work in ... industry
academia
both industry and academia Other (please specify)
2. In which company/institution do you work?
3. In which country do you work?
*4. What is your position within your company?
*5. How many years have you been employed in your company?
*6. How would you rate your background in the following programming paradigms? absent
weak
medium
good
strong
Object Oriented
Component Based
Service Oriented
Cloud Computing
*7. How would you rate your background in the following technologies? absent
weak
medium
good
strong
XSD/XML
WSDL
Restful
Page 2
Good and Bad Practices in Designing Stable Web APIs Background
Stability: is a quality attribute that measures the extent to which a web API will be stable over time and will not need changes. Metrics/quality indicators: are measures of the quality attributes of a software unit. Examples of such measures are: response time to estimate performance, number of changes per release to estimate stability, lines of code to estimate understandability, etc.
*8. Do you know any metrics/quality indicators to assess the stability of web APIs?
yes no
9. Which metrics/quality indicators do you know to assess the stability of web APIs?
Page 3
Good and Bad Practices in Designing Stable Web APIs Background
I agree! Background questions are really boring...you are few steps from the challenging part. Get your software engineering skills ready! Stability: measures the extent to which a web API will be stable over time and will not need changes. Usability: measures the ease with which a user can invoke the operations exposed in a web API and understand their purpose. Performance: measures the response time (how long it takes to process a request), throughput (how many requests overall can be processed per unit of time), or timeliness (ability to meet deadlines, i.e., to process a request in a deterministic and acceptable amount of time). Testability: measures the degree of effectiveness and efficiency with which test criteria can be established for a web API and tests can be performed to determine whether those criteria have been met.
*10. From your experience, which quality attributes should be usually satisfied while
designing web APIs? Please rank from 1 (most relevant attribute) to 5 (least relevant attribute)
Stability
Performance
Usability
Testability
*11. Usually you refactor web APIs because you want to... Never
Rarely
Sometimes
Often
Always
fix bugs
improve usability
improve performance
improve testability
improve stability
Other, please specify the reason plus its frequency (i.e., Never, Rarely, Sometimes, Often or Always)
Page 4
Good and Bad Practices in Designing Stable Web APIs FAT web APIs
Congratulations...you have completed the background part! It's time to have some fun! Let's warm up your brain! Have you ever heard about Fat web APIs? Should our web APIs be on a diet? Let's see what you think about its stability! I see ...'It depends' is the easier answer :) yet we want to challenge your thoughts...think about the most common scenarios! ;;) A Fat web API is a web API that exposes a large number of operations. Different clients invoke different and disjoint sets of its operations. In the example below, the BankInterface's clients invoke different and disjoint sets of the operations exposed.
Page 5
Good and Bad Practices in Designing Stable Web APIs
*12. In regard to quality attributes, how likely do you think a Fat web API would
change in the future?
Won't change
Might change
Likely to change
Very Likely to change
Sure will change
To improve usability
To improve performance
To improve testability
To improve stability
Other, please specify the quality attribute and the change frequency (i.e., Won't change, Might change, Likely to change, Very likely to change, Sure will change)
Page 6
Good and Bad Practices in Designing Stable Web APIs FAT web APIs
No idea about why a Fat web API can be unstable? Take a look at the following scenarios and tell us what you think! More ideas? Don't forget to use the text box at the bottom! A Fat web API is a web API that exposes a large number of operations. Different clients invoke different and disjoint sets of its operations. In the example below, the BankInterface's clients invoke different and disjoint sets of the operations exposed.
Page 7
Good and Bad Practices in Designing Stable Web APIs
*13. In regard to quality attributes, you think a Fat web API is likely to be changed in
the future because ... understanding the API is
Won't change
Might change
Likely to change
Very Likely to change
Sure will change
not easy for the clients because many operations are exposed having a specific method for each client would introduce clones and the API would become hard to be maintained it is likely to be a bottleneck, splitting it in two APIs specific for each client would improve the performance different developers work on the functionalities for the different clients if the functional requirements of a client change, the other client will be affected as well the test cases for both clients should pass before the API can be deployed Other, please specify the cause of the change plus its frequency (i.e., Won't change, Might change, Likely to change, Very likely to change, Sure will change)
Page 8
Good and Bad Practices in Designing Stable Web APIs Multiservice web API
Nice job! You have 3 design practices and 1 metric left. Let's see what you think about the Multiservice! A Multiservice web API is an API that exposes operations associated to different business entities. The following example shows a Multiservice API with operations associated to three different business entities (i.e., payment, order and inventory).
*14. In regard to quality attributes, how likely do you think a Multiservice web API
would change in the future?
Won't change
Might change
Likely to change
Very Likely to change
Sure will change
To improve usability
To improve performance
To improve testability
To improve stability
Other, please specify the quality attribute and the change frequency (i.e., Won't change, Might change, Likely to change, Very likely to change, Sure will change)
Page 9
Good and Bad Practices in Designing Stable Web APIs Multiservice web API
Mmm....I'm curious to know if your thoughts considered these scenarios in the previous page... A Multiservice web API is an API that exposes operations associated to different business entities. The following example shows a Multiservice API with operations associated to three different business entities (i.e., payment, order and inventory).
Page 10
Good and Bad Practices in Designing Stable Web APIs
*15. In regard to quality attributes, you think a Multiservice web API is likely to be
changed in the future because ... the different business
Won't change
Might change
Likely to change
Very Likely to change
Sure will change
entities can change for different reasons when a business entity changes the clients coupled with operations associated to other entities are affected by the changes as well all the tests involving the different entities should pass before the entire service is deployed of the different business entities the number of invocations to the Multiservice web API increases of the numerous clients a proper pool tuning is needed to achieve adequate performance different developers work on different business entities many business entities are exposed that complicate the understanding of the API Other, please specify the cause of the change plus its frequency (i.e., Won't change, Might change, Likely to change, Very likely to change, Sure will change)
Page 11
Good and Bad Practices in Designing Stable Web APIs Tiny web API
Have you already refactored the Multiservice APIs? Have you refactored them into Tiny APIs? Is it better or not? A TinyService is a web API that represents only part of an abstraction and exposes a subset of the necessary operations. In the example below the abstraction Order is represented by three Tiny services.
*16. In regard to quality attributes, how likely do you think a Tiny web API would
change in the future?
Won't change
Might change
Likely to change
Very Likely to change
Sure will change
To improve usability
To improve performance
To improve testability
To improve stability
Other, please specify the quality attribute and the change frequency (i.e., Won't change, Might change, Likely to change, Very likely to change, Sure will change)
Page 12
Good and Bad Practices in Designing Stable Web APIs Tiny web API
Few evolution scenarios and you'll reach the last design practices ;;) A TinyService is a web API that represents only part of an abstraction and exposes a subset of the necessary operations. In the example below the abstraction Order is represented by three Tiny services.
*17. In regard to quality attributes you think the tiny web APIs are likely to be changed
in the future because ...
Won't occur
Might occur
Likely to occur
Very likely to occur
Sure will occur
implementation and maintenance requires changes to multiple web APIs developers should know which web API operate together testing and validating a business abstraction requires testing of multiple web APIs performance may suffer with a large number of web APIs
Other, please specify the cause of the change plus its frequency (i.e., Won't occur, Might occur, Likely to occur, Very likely to occur, Sure will occur)
Page 13
Good and Bad Practices in Designing Stable Web APIs SandPile web API
Great job! I hope you're challenging your thoughts...and I'm sure you're curious about the last design practices...ladies and gentlemen...the well known SandPile!! A SandPile is a web API that exposes multiple fine-grained operations. In the example below the service Address is published as a CRUD (create, read, update, and delete) web API.
*18. In regard to quality attributes, how likely do you think a Sand Pile web API would
change in the future?
Won't change
Might change
Likely to change
Very Likely to change
Sure will change
To improve usability
To improve performance
To improve testability
To improve stability
Other, please specify the quality attribute and the change frequency (i.e., Won't change, Might change, Likely to change, Very likely to change, Sure will change)
Page 14
Good and Bad Practices in Designing Stable Web APIs SandPile web API
Wow...the last evolution scenarios...don't forget you can add more in the text box. A SandPile is a web API that exposes multiple fine-grained operations. In the example below the service Address is published as a CRUD (create, read, update, and delete) web API.
*19. In regard to quality attributes, you think a Sand Pile web API is likely to be
changed in the future because ... if the API is exposed as a
Won't occur
Might occur
Likely to occur
Very likely to occur
Sure will occur
RESTful web API clients should invoke multiple procedures increasing execution time if the API is exposed as a WSDL web API clients should invoke multiple procedures increasing execution time business logic is usually implemented in the client limiting its reuse it has many operations and it’s confusing for the clients' developers Other, please specify the cause of the change plus its frequency (i.e., Won't occur, Might occur, Likely to occur, Very likely to occur, Sure will occur)
Page 15
Good and Bad Practices in Designing Stable Web APIs
Congratulations...you have completed the design practices part...just few questions about cohesion and you've done!
*20. The figure below shows a simple WSDL API, are you familiar with WSDL APIs?
yes no
Page 16
Good and Bad Practices in Designing Stable Web APIs Cohesion in web APIs
Congratulations...you have completed the design practices part...just few questions about cohesion and you've done! Similar to the Lack of Cohesion in Methods (LCOM) proposed for the object oriented paradigm, Lack of Cohesion in Services (LCOS) measures the data cohesion of a WSDL API. A WSDL API is considered cohesive if the operations reference the same messages. In the figure below the operations, messages and types of three generic WSDL APIs are shown. For the sake of simplicity we report only the elements needed for computing the cohesion. Elements shared by the two operations are highlighted in orange. According to LCOS the WSDL1 and WSDL3 are non-cohesive because their operations do not refer to the same message. WSDL2 is considered cohesive because their operations refer to the same message.
Page 17
Good and Bad Practices in Designing Stable Web APIs
*21. How useful do you think LCOS is for measuring the cohesion of a WSDL API? Very useless
Useless
Useful but it needs improvements
Useful
Very useful
*22. Should data types be taken into account to compute the cohesion?
Yes No
Other (please specify)
*23. Do you think the WSDL3 API in the example above is cohesive?
yes no
*24. In regard to the data types in WSDL3, which data type are more likely to be
changed in the future? shared data types
not shared data types
*25. Please, motivate briefly your choice. Why do you think shared or not shared data
types are more likely to be changed?
Page 18
Good and Bad Practices in Designing Stable Web APIs External Cohesion and web APIs
Again cohesion??? Yup, but this is external and we need your expertise to understand why it can affect the stability of a web API. The external cohesion metric measures the degree to which the clients of a web API invoke the same operations. In the examples below, the BankInterface web API is non-externally cohesive because its clients invoke different operations. Only one operation out of five are invoked by both clients.
*26. Which operations are more likely to be changed? operations invoked by multiple clients (e.g., requestInsurance)
operations invoked only by a specific client (e.g.,requestLoanForStudent )
*27. In regard to the previous question, please describe the main reason(s) why the
operations might change.
Page 19
Good and Bad Practices in Designing Stable Web APIs
*28. In regard to quality attributes, how likely do you think a non-externally cohesive
web API would change in the future? Won't change
Might change
Likely to change
Very Likely to change
Sure will change
To improve usability
To improve performance
To improve testability
To improve stability
Other, please specify the quality attribute plus the change frequency (i.e., Won't change, Might change, Likely to change, Very likely to change, Sure will change)
*29. In regard to quality attributes, please describe the main reason(s) why a non- externally cohesive web API might change.
Page 20
Good and Bad Practices in Designing Stable Web APIs Further practices in designing stable web API
mmm...it seems your brain went beyond our proposed design practices! Can you suggest any further practices?
30. What are the best practices in designing stable web APIs that were not covered by this survey?
31. What are the worst practices in designing stable web APIs that were not covered by this survey?
Page 21
Good and Bad Practices in Designing Stable Web APIs Conclusion
That was an amazing job! I still have to collect more results and analyze them but I'm sure your contribution is essential! Almost time to say goodbye :(
*32. Did you find this survey challenging?
yes no
*33. Did you enjoy this survey? Not at all
No
Yes
I wish it was longer
*34. Did you know the design practices covered in this survey? none
few
some
all
35. It's time to WIN....fill in your email address if you want to win one of the five 20€ Amazon vouchers
*36. Are you eager to know the results or participate in further studies? Answer yes (and be sure you entered your email address above) or send an email to Daniele Romano with "[I need stable web APIs]" as subject at a later time.
yes no
Thanks for having participated in this survey! Daniele Romano, MSc PhD Candidate ---------------------------------------------------------- Software Engineering Research Group Delft University of Technology Email:
[email protected] Tel. +31(0)152786338
Page 22
![RESTful Web Services - RESTful Web APIs [PDF]](https://m.moam.info/img/260x300/restful-web-services-restful-web-apis-pdf_6498ba9f098a9ef41a8b4684.jpg)
