Quality criteria for APIs

[Erik Andersson]

Hi! I´m looking for inspiration in defining quality standards for APIs targeted for different audiences. Imagine we have four different API target audiences: (1) Internal low effort, (2) Internal, (3) External partners & (4) External Customers.

What could the quality standards be for these different audiences? Online references, books, whatever .. are greatly appreciated.

Kind regards, Erik

[Erik Andersson]

More info, I basically want to learn more about what these standards can be in terms of "discoverability, changeability, quality of design and documentation, as well as permission granting". Below is a citation from Zalando

".. each API must be classified with respect to the intended target audience supposed to consume the API, to facilitate differentiated standards on APIs for discoverability, changeability, quality of design and documentation, as well as permission granting. We differentiate the following API audience groups with clear organisational and legal boundaries.”

[nishant mahajan]

+1 as I am a qa engineer looking for api quality topics

Thanks & Regards

It would be great

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/api-craft/d48762d4-f2ee-4db5-a904-f41b43ded300%40googlegroups.com.

[Derric Gilling]

Here are some of my favorite blogs on APIs:

https://nordicapis.com/ 

http://apiguide.io 

https://apifriends.com/ 

https://www.devmarketingguide.com/ 

https://apievangelist.com/ 

https://www.moesif.com/blog/ 

https://idratherbewriting.com/ 

https://www.programmableweb.com/ 

Note: Moesif is our own blog on APIs and API Product Management. 

Derric

To view this discussion on the web visit https://groups.google.com/d/msgid/api-craft/CANLik8CG-TP9MH9pkYSSGXTY%3D_v%2BEi1Kp6umkG9P%2BE1%2BW__jUw%40mail.gmail.com.

[MatthewReinbold]

Hello Erik!

Quality standards for API design "-ilities" - readability, maintainability, integratability (?) - have been tricky. I lead the Platform Services Center of Excellence at a Fortune 500 company. I lead the team responsible for standards, processes, and training for our approximately 9000 developers working on APIs. Like you, we have different "categories" of APIs: low-level architectural constructs known and utilized only within the team themselves, common building blocks for the company, and external partner integrations. I've pushed a handful of thoughts on the process over the years. 

In 2017, we had the notions of "conformance" (adherence to standards), "performance", and "transformation". More on that breakdown here:
https://matthewreinbold.com/2017/10/03/API-Governance-Blueprint/

Getting numbers for comparison for "transformative" relied on subjective judgement. While we had world class experts evaluating the designs, there were problems in using NPS as a rating scale. This is something I documented here:
https://matthewreinbold.com/2018/07/10/Update-on-NPS/

It has been awhile since I've posted an update on how our thinking has evolved on the matter. An incredible resource that I can't stop promoting is the book "Platform Ecosystems: Aligning Architecture, Governance, and Strategy", by Amrit Tiwana. While it is about platforms, like mobile app stores, it does discuss impacts of high and low quality design on a platform's success, what to measure, and how to incentivize the proper behavior. Ultimately, if you are in the position to create, audit, and report on metrics to generate outcomes, some platform thinking might generate some insights. 

[Nishant Mahajan]

is there any blog related to api testing

To view this discussion on the web visit https://groups.google.com/d/msgid/api-craft/C93ED46D-ED0A-4BC1-87C7-74A526F480D9%40moesif.com.

The information in this message may be confidential and is intended only for the individual to whom it is addressed. If you are not the intended recipient of this message, you are hereby notified that any use, review, retransmission, dissemination, distribution, or reproduction of this communication is strictly prohibited. If this message was received in error, please immediately notify the sender and delete or destroy any copy of it.

[Derric Gilling]

Hmm, I haven’t seen one specific to API testing, although some of the blogs below do have some content on it.

I personally like the content NordicAPI. Some on API testing are below:

https://nordicapis.com/9-best-practices-for-rest-api-testing/

https://nordicapis.com/7-tips-on-api-monitoring/

https://nordicapis.com/9-types-of-tests-to-perform-on-your-apis/

https://nordicapis.com/9-common-errors-made-during-api-testing/

https://nordicapis.com/tips-and-tools-for-debugging-apis/

We also wrote some content on API testing, mostly on how to use a test runner like Runscope or Postman with an analytics system like Moesif. 

https://www.moesif.com/blog/companies/runscope/Debugging-Runscope-Tests-using-Variables-and-Moesif-Segmentation/ 

https://www.moesif.com/blog/technical/api-testing/How-to-Automate-Creating-API-Tests-for-Postman-with-Moesif/ 

Postman and Runscope might have some good content on their respective blogs on API testing also. 

Thanks,

Derric

To view this discussion on the web visit https://groups.google.com/d/msgid/api-craft/CAFb3i1EtYb4nQrU%3DNu7CRxLjYooz291P3jnjo_p2TX_AEQZzqg%40mail.gmail.com.

[Erik Andersson]

Thanks for all the feedback! MatthewReinbold really interesting reads at your blog! Will order the book later tonight. I like the idea of observing how the organization performs as a complex system. In that regard I think there were some good points in Continuous API Management http://shop.oreilly.com/product/0636920201755.do

What I mean by "quality criteria" is the level of effort in terms of for example design, implementation, testing, change control that APIs targeted for different audiences must adhere to. 

• E.g. for internal APIs you may want to get influence from the enterprise information model, whereas for external APIs the primary source of inspiration may instead be industry standards. And for  APIs with few consumers and limited lifetime, it´s probably not motivated to invest any time at all in aligning the design to any information model. 
• Or another example related to change control - when building an external API and there´s some change, then the change may have to go through some impact analysis prior to deployment, or perhaps some program manager signoff (just thinking out loud).
• Requirement to target a certain level of REST maturity model may be another differentiating factor

Basically, I want to define really clear quality criteria that may be different depending on the target audience. The criteria should cover the entire lifespan/lifecycle of an API dealing with both build and management requirements (e.g. who is allowed to change API x to a new major version)

Thanks all! /Erik

[Adrita Bhor]

For api testing, check out Postman's blog at: https://blog.postman.com/ and tutorials https://blog.postman.com/tutorials/

To view this discussion on the web visit https://groups.google.com/d/msgid/api-craft/CAFb3i1EtYb4nQrU%3DNu7CRxLjYooz291P3jnjo_p2TX_AEQZzqg%40mail.gmail.com.

[Erik Andersson]

Hi again! I wasn´t in my sharpest mood when I wrote my last reply. So, I´ll try to be a bit more concise. I´m looking for quality criteria than covers requirements in both API standards and process, that may be different depending on the targeted audience. 

Thanks! Erik

[Erik Wilde]

hello erik.

thanks for kicking off a good thread!

On 2020-03-09 03:58, Erik Andersson wrote:
> Hi again! I wasn´t in my sharpest mood when I wrote my last reply. So,
> I´ll try to be a bit more concise. I´m looking for quality criteria than
> covers requirements in both API standards and process, that may be
> different depending on the targeted audience.

i am currently compiling a list of open source guidelines. some of them
have process bits to it, but not all of them.

https://dret.github.io/guidelines/

if you find any open ones you find inspiring not already on this list,
please let me know.

i am planning to spend more time with all of this over the summer. part
of it is because we're working on our internal guidelines at here at
axway, and part of it is because i'd like to have something i can give
our customers, because most of them have the same questions that you have.

my current thinking is that

- guidelines should be structured (why they exist, what to do about
them, how to implement it, and how to test for it) and have a process
model that is firmly grounded in community driven contributions,
- there should be underlying models of an API lifecycle, and of classes
of APIs (internal, partner, external),
- something akin to RFC 2119 should handle requirement levels, and
- each guideline must specify acceptance criteria and as many as
possible should be automated and added to standard development pipelines.

one thing i like a lot is google's AIP process. it's a bit odd to me how
exactly it connects with their guidelines (which were created prior to
the AIP process), but i think what has happened there is what's typical
for most orgs: they started with the guidelines, and then realized that
they need to evolve them, and that they need some process around how to
evolve them.

matthew's description is close to what google does (i think), but google
may have more published information about their process that you can
look at for inspiration. have a look here: https://aip.dev/

cheers,

dret.

--
erik wilde | mailto:erik....@dret.net |
| http://dret.net/netdret |
| http://twitter.com/dret |

[Erik Andersson]

Much appreciated! Thank you!

erik wilde | mailto:erik...@dret.net |
            | http://dret.net/netdret    |
            | http://twitter.com/dret    |