Download to read offline
![978-1-492-04355-3
[LSI]
Continuous API Management
by Mehdi Medjaoui, Erik Wilde, Ronnie Mitra, and Mike Amundsen
Copyright © 2019 Mehdi Medjaoui, Erik Wilde, Ronnie Mitra, and Mike Amundsen. All rights reserved.
Printed in the United States of America.
Published by O’Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472.
O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are
also available for most titles (http://oreilly.com/safari). For more information, contact our corporate/insti‐
tutional sales department: 800-998-9938 or corporate@oreilly.com.
Editor: Alicia Young Indexer: WordCo Indexing Services, Inc.
Production Editor: Justin Billing Interior Designer: David Futato
Copyeditor: Rachel Head Cover Designer: Karen Montgomery
Proofreader: James Fraleigh Illustrators: Rebecca Demarest and Ronnie Mitra
November 2018: First Edition
Revision History for the First Edition
2018-11-14: First Release
See http://oreilly.com/catalog/errata.csp?isbn=9781492043553 for release details.
The O’Reilly logo is a registered trademark of O’Reilly Media, Inc. Continuous API Management, the
cover image, and related trade dress are trademarks of O’Reilly Media, Inc.
The views expressed in this work are those of the authors, and do not represent the publisher’s views.
While the publisher and the authors have used good faith efforts to ensure that the information and
instructions contained in this work are accurate, the publisher and the authors disclaim all responsibility
for errors or omissions, including without limitation responsibility for damages resulting from the use of
or reliance on this work. Use of the information and instructions contained in this work is at your own
risk. If any code samples or other technology this work contains or describes is subject to open source
licenses or the intellectual property rights of others, it is your responsibility to ensure that your use
thereof complies with such licenses and/or rights.](https://image.slidesharecdn.com/5748477-250529164254-f6ea82bb/75/Continuous-Api-Management-Making-The-Right-Decisions-In-An-Evolving-Landscape-Mike-Amundsen-8-2048.jpg)
![Angular.js, Node.js] developer or some other variation on the idea of a single devel‐
oper that has skills for all aspects of your API program. You also may hear lots of talk
about “startup teams” or “self-contained teams.” It all boils down to having all the
skills you need in one team.
This makes sense when your APIs are few and they all are designed and implemented
using the same set of tools (see “Technology” on page 11). But as the scale and scope
of your API program grows, the number of skills required to build and maintain your
APIs gross, too. You can no longer expect each API team to consist of a set number
of people with skills in design, database, backend, frontend, testing, and deployment.
You might have a team whose job is to design and build a data-centric dashboard
interface used by a wide range of other teams. Their skills may, for example, need to
cover all the data formats used and tools needed to collect that data. Or you might
have a team whose primary job is to build mobile apps that use a single technology
like GraphQL or some other query-centric library. As technological variety grows,
your teams may need to become more specialized. We’ll have a chance to explore this
in detail later, in Chapter 7.
Another way in which teams will need to change as your API landscape grows is the
way in which they participate in day-to-day decision-making processes. When you
have a small number of teams and their experience is not very deep, it can make sense
to centralize the decision making to a single, guiding group. In large organizations
this is often the Enterprise Architecture group or something with a similar name.
This works at smaller scales and scopes but becomes a big problem as your ecosystem
becomes less homogeneous and more wide-ranging. As tech gets more involved, a
single team is unlikely to be able to keep up with the details of each tool and frame‐
work. And as you add more and more teams, decision making itself needs to be dis‐
tributed; a central committee rarely understands the realities of the day-to-day
operations in a global enterprise.
The solution is to break down the decision-making process into what we call decision
elements (see “The Elements of a Decision” on page 27) and distribute those elements
to the proper levels within your company. A growing ecosystem means teams need to
become more specialized on a technical level and more responsible at the decision-
making level.
Governance
The last area that we want to touch on in regards to the challenge of API landscapes
is the general approach to governance of your API program. Again, as in other cases
mentioned here, it is our observation that the role and levers of governance will
change as your ecosystem grows. New challenges appear, and old methods are not as
effective as they were in the past. In fact, especially at the enterprise level, sticking to
old governance models can slow or even stall the success of your APIs.
12 | Chapter 1: The Challenge of API Management](https://image.slidesharecdn.com/5748477-250529164254-f6ea82bb/75/Continuous-Api-Management-Making-The-Right-Decisions-In-An-Evolving-Landscape-Mike-Amundsen-36-2048.jpg)
![Chapter 3
Of the rebellion at Suya and the reasons the settlers gave for it.
We have already stated in the last chapter that Don Garcia Lopez de
Cardenas came back from Suya in flight, having found that country
risen in rebellion. He told how and why that town was deserted,
which occurred as I will relate. The entirely worthless fellows were
all who had been left in that town, the mutinous and seditious men,
besides a few who were honored with the charge of public affairs
and who were left to govern the others. Thus the bad dispositions of
the worthless secured the power, and they held daily meetings and
councils and declared that they had been betrayed and were not
going to be rescued, since the others had been directed to go
through another part of the country, where there was a more
convenient route to New Spain, which was not so, because they
were still almost on the direct road. This talk led some of them to
revolt, and they chose one Pedro de Avila as their captain. They
went back to Culiacan, leaving the captain, Diego de Alcaraz, sick in
the town of San Hieronimo, with only a small force. He did not have
anyone whom he could send after them to compel them to return.
They killed a number of people at several villages along the way.
Finally they reached Culiacan, where Hernando Arias de Saabedra,
[540]
who was waiting for Juan Gallego to come back from New Spain
with a force, detained them by means of promises, so that Gallego
could take them back. Some who feared what might happen to them
ran away one night to New Spain. Diego de Alcaraz, who had
remained at Suya with a small force, sick, was not able to hold his
position, although he would have liked to, on account of the
poisonous herb which the natives use.[541]
When these noticed how
weak the Spaniards were, they did not continue to trade with them
as they formerly had done. Veins of gold had already been](https://image.slidesharecdn.com/5748477-250529164254-f6ea82bb/75/Continuous-Api-Management-Making-The-Right-Decisions-In-An-Evolving-Landscape-Mike-Amundsen-58-2048.jpg)
![discovered before this, but they were unable to work these, because
the country was at war. The disturbance was so great that they did
not cease to keep watch and to be more than usually careful.
The town was situated on a little river.[542]
One night they suddenly
saw fires which they were not accustomed to, and on this account
they doubled the watches, but not having noticed anything during
the whole night, they grew careless along toward morning, and the
enemy entered the village so silently that they were not seen until
they began to kill and plunder. A number of men reached the plain
as well as they could, but while they were getting out the captain
was mortally wounded. Several Spaniards came back on some
horses after they had recovered themselves and attacked the enemy,
rescuing some, though only a few. The enemy went off with the
booty, leaving three Spaniards killed[543]
besides many of the
servants and more than twenty horses.
The Spaniards who survived started off the same day on foot, not
having any horses. They went toward Culiacan, keeping away from
the roads, and did not find any food until they reached Corazones
where the Indians, like the good friends they have always been,
provided them with food. From here they continued to Culiacan,
undergoing great hardships. Hernandarias de Saabedra, the mayor,
received them and entertained them as well as he could until Juan
Gallego arrived with the reinforcements which he was conducting, on
his way to find the army. He was not a little troubled at finding that
post deserted, when he expected that the army would be in the rich
country which had been described by the Indian called Turk,
because he looked like one.](https://image.slidesharecdn.com/5748477-250529164254-f6ea82bb/75/Continuous-Api-Management-Making-The-Right-Decisions-In-An-Evolving-Landscape-Mike-Amundsen-59-2048.jpg)
![Chapter 4
Of how Friar Juan de Padilla and Friar Luis remained in the
country and the army prepared to return to Mexico.
When the general, Francisco Vasquez, saw that everything was now
quiet, and that his schemes had gone as he wished, he ordered that
everything should be ready to start on the return to New Spain by
the beginning of the month of April, in the year 1543 [1542].
Seeing this, Friar Juan de Padilla, a regular brother of the lesser
order, and another, Friar Luis,[544]
a lay brother, told the general that
they wanted to remain in that country—Friar Juan de Padilla in
Quivira, because his teachings seemed to promise fruit there, and
Friar Luis at Cicuye. On this account, as it was Lent at the time, the
father made this the subject of his sermon to the companies one
Sunday, establishing his proposition on the authority of the Holy
Scriptures. He declared his zeal for the conversion of these peoples
and his desire to draw them to the faith, and stated that he had
received permission to do it, although this was not necessary. The
general sent a company to escort them as far as Cicuye, where Friar
Luis stopped, while Friar Juan went on back to Quivira with the
guides who had conducted the general, taking with him the
Portuguese, as we related, and the half-blood, and the Indians from
New Spain. He was martyred a short time after he arrived there, as
we related in the second part, Chapter 8. Thus we may be sure that
he died a martyr, because his zeal was holy and earnest.
Friar Luis remained at Cicuye. Nothing more has been heard about
him since, but before the army left Tiguex some men who went to
take him a number of sheep that were left for him to keep, met him
as he was on his way to visit some other villages, which were fifteen
or twenty leagues from Cicuye, accompanied by some followers. He](https://image.slidesharecdn.com/5748477-250529164254-f6ea82bb/75/Continuous-Api-Management-Making-The-Right-Decisions-In-An-Evolving-Landscape-Mike-Amundsen-60-2048.jpg)
![felt very hopeful that he was liked at the village and that his
teaching would bear fruit, although he complained that the old men
were falling away from him. I, for my part, believe that they finally
killed him. He was a man of good and holy life, and may Our Lord
protect him and grant that he may convert many of those peoples,
and end his days in guiding them in the faith. We do not need to
believe otherwise, for the people in those parts are pious and not at
all cruel. They are friends, or rather, enemies of cruelty, and they
remained faithful and loyal friends.[545]
After the friars had gone, the general, fearing that they might be
injured if people were carried away from that country to New Spain,
ordered the soldiers to let any of the natives who were held as
servants go free to their villages whenever they might wish. In my
opinion, though I am not sure, it would have been better if they had
been kept and taught among Christians.
The general was very happy and contented when the time arrived
and everything needed for the journey was ready, and the army
started from Tiguex on its way back to Cibola. One thing of no small
note happened during this part of the trip. The horses were in good
condition for their work when they started, fat and sleek, but more
than thirty died during the ten days which it took to reach Cibola,
and there was not a day in which two or three or more did not die. A
large number of them also died afterward before reaching Culiacan,
a thing that did not happen during all the rest of the journey.
After the army reached Cibola, it rested before starting across the
wilderness, because this was the last of the settlements in that
country. The whole country was left well disposed and at peace, and
several of our Indian allies remained there.[546]](https://image.slidesharecdn.com/5748477-250529164254-f6ea82bb/75/Continuous-Api-Management-Making-The-Right-Decisions-In-An-Evolving-Landscape-Mike-Amundsen-61-2048.jpg)
![occurred. Those soldiers who had come from the new lands would
not agree to anything except the return to New Spain, so that
nothing came of the proposals made at the consultations, and
although there was some opposition, they were finally quieted.
Several of the mutineers who had deserted the town of Corazones
came with Juan Gallego, who had given them his word as surety for
their safety, and even if the general had wanted to punish them, his
power was slight, for he had been disobeyed already and was not
much respected. He began to be afraid again after this, and made
himself sick, and kept a guard. In several places yells were heard
and Indians seen, and some of the horses were wounded and killed,
before Batuco[547]
was reached, where the friendly Indians from
Corazones came to meet the army and see the general. They were
always friendly and had treated all the Spaniards who passed
through their country well, furnishing them with what food they
needed, and men, if they needed these. Our men had always treated
them well and repaid them for these things. During this journey the
juice of the quince was proved to be a good protection against the
poison of the natives, because at one place, several days before
reaching Señora, the hostile Indians wounded a Spaniard called
Mesa, and he did not die, although the wound of the fresh poison is
fatal, and there was a delay of over two hours before curing him
with the juice. The poison, however, had left its mark upon him. The
skin rotted and fell off until it left the bones and sinews bare, with a
horrible smell. The wound was in the wrist, and the poison had
reached as far as the shoulder when he was cured. The skin on all
this fell off.
The army proceeded without taking any rest, because the provisions
had begun to fail by this time. These districts were in rebellion, and
so there were not any victuals where the soldiers could get them
until they reached Petlatlan, although they made several forays into
the cross country in search of provisions. Petlatlan is in the province
of Culiacan, and on this account was at peace, although they had
several surprises after this.[548]
The army rested here several days to
get provisions. After leaving here they were able to travel more](https://image.slidesharecdn.com/5748477-250529164254-f6ea82bb/75/Continuous-Api-Management-Making-The-Right-Decisions-In-An-Evolving-Landscape-Mike-Amundsen-63-2048.jpg)
![Chapter 6
Of how the general started from Culiacan to give the viceroy an
account of the army with which he had been intrusted.
It seemed, indeed, as if the arrival in the valley of Culiacan had
ended the labors of this journey, partly because the general was
governor there and partly because it was inhabited by Christians. On
this account some began to disregard their superiors and the
authority which their captains had over them, and some captains
even forgot the obedience due to their general. Each one played his
own game, so that while the general was marching toward the town,
which was still ten leagues away, many of the men, or most of them,
left him in order to rest in the valley, and some even proposed not to
follow him. The general understood that he was not strong enough
to compel them, although his position as governor gave him fresh
authority. He determined to accomplish it by a better method, which
was to order all the captains to provide food and meat from the
stores of several villages that were under his control as governor. He
pretended to be sick, keeping his bed, so that those who had any
business with him could speak to him or he with them more freely,
without hindrance or observation, and he kept sending for his
particular friends in order to ask them to be sure to speak to the
soldiers and encourage them to accompany him back to New Spain,
and to tell them that he would request the viceroy, Don Antonio de
Mendoza, to show them especial favor, and that he would do so
himself for those who might wish to remain in his government. After
this had been done, he started with his army at a very bad time,
when the rains were beginning, for it was about Saint John's day,[549]
at which season it rains continuously. In the uninhabited country
which they passed through as far as Compostela there are numerous
very dangerous rivers, full of large and fierce alligators. While the](https://image.slidesharecdn.com/5748477-250529164254-f6ea82bb/75/Continuous-Api-Management-Making-The-Right-Decisions-In-An-Evolving-Landscape-Mike-Amundsen-65-2048.jpg)
![army was halting at one of these rivers, a soldier who was crossing
from one side to the other was seized, in sight of everybody, and
carried off by an alligator without its being possible to help him. The
general proceeded, leaving the men who did not want to follow him
all along the way, and reached Mexico with less than 100 men. He
made his report to the viceroy, Don Antonio de Mendoza, who did
not receive him very graciously, although he gave him his discharge.
His reputation was gone from this time on. He kept the government
of New Galicia, which had been entrusted to him, for only a short
time, when the viceroy took it himself, until the arrival of the court,
or audiencia, which still governs it. And this was the end of those
discoveries and of the expedition which was made to these new
lands.
It now remains for us to describe the way in which to enter the
country by a more direct route, although there is never a short cut
without hard work. It is always best to find out what those know
who have prepared the way, who know what will be needed. This
can be found elsewhere, and I will now tell where Quivira lies, what
direction the army took, and the direction in which Greater India lies,
which was what they pretended to be in search of, when the army
started thither. Today, since Villalobos[550]
has discovered that this
part of the coast of the South Sea trends toward the west, it is
clearly seen and acknowledged that, since we were in the north, we
ought to have turned to the west instead of toward the east, as we
did. With this, we will leave this subject and will proceed to finish
this treatise, since there are several noteworthy things of which I
must give an account, which I have left to be treated more
extensively in the two following chapters.](https://image.slidesharecdn.com/5748477-250529164254-f6ea82bb/75/Continuous-Api-Management-Making-The-Right-Decisions-In-An-Evolving-Landscape-Mike-Amundsen-66-2048.jpg)
![people to punish them for their rebellion. He did not lose a
companion during all this, nor was anyone wounded, except one
soldier, who was wounded in the eyelid by an Indian who was almost
dead, whom he was stripping. The weapon broke the skin and, as it
was poisoned, he would have had to die if he had not been saved by
the quince juice; he lost his eye as it was. These deeds of theirs
were such that I know those people will remember them as long as
they live, and especially four or five friendly Indians who went with
them from Corazones, who thought that they were so wonderful that
they held them to be something divine rather than human.[551]
If he
had not fallen in with our army as he did, they would have reached
the country of the Indian called Turk, which they expected to march
to, and they would have arrived there without danger on account of
their good order and the skill with which he was leading them, and
their knowledge and ample practice in war. Several of these men are
still in this town of Culiacan, where I am now writing this account
and narrative, where they, as well as I and the others who have
remained in this province, have never lacked for labor in keeping this
country quiet, in capturing rebels, and increasing in poverty and
need, and more than ever at the present hour, because the country
is poorer and more in debt than ever before.](https://image.slidesharecdn.com/5748477-250529164254-f6ea82bb/75/Continuous-Api-Management-Making-The-Right-Decisions-In-An-Evolving-Landscape-Mike-Amundsen-69-2048.jpg)
![Now that I wish to describe the appearance of the bulls, it is to be
noticed first that there was not one of the horses that did not take
flight when he saw them first, for they have a narrow, short face,
the brow two palms across from eye to eye, the eyes sticking out at
the side, so that, when they are running, they can see who is
following them. They have very long beards, like goats, and when
they are running they throw their heads back with the beard
dragging on the ground. There is a sort of girdle round the middle of
the body. The hair is very woolly, like a sheep's, very fine, and in
front of the girdle the hair is very long and rough like a lion's. They
have a great hump, larger than a camel's. The horns are short and
thick, so that they are not seen much above the hair. In May they
change the hair in the middle of the body for a down, which makes
perfect lions of them. They rub against the small trees in the little
ravines to shed their hair, and they continue this until only the down
is left, as a snake changes his skin. They have a short tail, with a
bunch of hair at the end. When they run, they carry it erect like a
scorpion. It is worth noticing that the little calves are red and just
like ours, but they change their color and appearance with time and
age.
Another strange thing was that all the bulls that were killed had their
left ears slit, although these were whole when young. The reason for
this was a puzzle that could not be guessed. The wool ought to
make good cloth on account of its fineness, although the color is not
good, because it is the color of buriel.[552]
Another thing worth noticing is that the bulls travelled without cows
in such large numbers that nobody could have counted them, and so
far away from the cows that it was more than forty leagues from
where we began to see the bulls to the place where we began to see
the cows. The country they travelled over was so level and smooth
that if one looked at them the sky could be seen between their legs,
so that if some of them were at a distance they looked like smooth-
trunked pines whose tops joined, and if there was only one bull it
looked as if there were four pines. When one was near them, it was
impossible to see the ground on the other side of them. The reason](https://image.slidesharecdn.com/5748477-250529164254-f6ea82bb/75/Continuous-Api-Management-Making-The-Right-Decisions-In-An-Evolving-Landscape-Mike-Amundsen-71-2048.jpg)
![for all this was that the country seemed as round as if a man should
imagine himself in a three-pint measure, and could see the sky at
the edge of it, about a crossbow shot from him, and even if a man
only lay down on his back he lost sight of the ground.
I have not written about other things which were seen nor made any
mention of them, because they were not of so much importance,
although it does not seem right for me to remain silent concerning
the fact that they venerate the sign of the cross in the region where
the settlements have high houses. For at a spring which was in the
plain near Acuco they had a cross two palms high and as thick as a
finger, made of wood with a square twig for its crosspiece, and many
little sticks decorated with feathers around it, and numerous
withered flowers, which were the offerings.[553]
In a graveyard
outside the village at Tutahaco there appeared to have been a recent
burial. Near the head there was another cross made of two little
sticks tied with cotton thread, and dry withered flowers.[554]
It
certainly seems to me that in some way they must have received
some light from the cross of Our Redeemer, Christ, and it may have
come by way of India, from whence they proceeded.](https://image.slidesharecdn.com/5748477-250529164254-f6ea82bb/75/Continuous-Api-Management-Making-The-Right-Decisions-In-An-Evolving-Landscape-Mike-Amundsen-72-2048.jpg)
![Chapter 9
Which treats of the direction which the army took, and of how another more
direct way might be found, if anyone was to return to that country.
I very much wish that I possessed some knowledge of cosmography
or geography, so as to render what I wish to say intelligible, and so
that I could reckon up or measure the advantage those people who
might go in search of that country would have if they went directly
through the centre of the country, instead of following the road the
army took. However, with the help of the favor of the Lord, I will
state it as well as I can, making it as plain as possible.
It is, I think, already understood that the Portuguese, Campo, was
the soldier who escaped when Friar Juan de Padilla was killed at
Quivira, and that he finally reached New Spain from Panuco,[555]
having travelled across the plains country until he came to cross the
North Sea mountain chain, keeping the country that Don Hernando
de Soto discovered all the time on his left hand, since he did not see
the river of the Holy Spirit (Espiritu Santo) at all.[556]
After he had
crossed the North Sea mountains, he found that he was in Panuco,
so that if he had not tried to go to the North Sea, he would have
come out in the neighborhood of the border land, or the country of
the Sacatecas,[557]
of which we now have some knowledge.
This way would be somewhat better and more direct for anyone
going back there in search of Quivira, since some of those who came
with the Portuguese are still in New Spain to serve as guides.
Nevertheless, I think it would be best to go through the country of
the Guachichules,[558]
keeping near the South Sea mountains all the
time, for there are more settlements and a food supply, for it would
be suicide to launch out on to the plains country, because it is so
vast and is barren of anything to eat, although, it is true, there
would not be much need of this after coming to the cows. This is](https://image.slidesharecdn.com/5748477-250529164254-f6ea82bb/75/Continuous-Api-Management-Making-The-Right-Decisions-In-An-Evolving-Landscape-Mike-Amundsen-73-2048.jpg)
![only when one goes in search of Quivira, and of the villages which
were described by the Indian called Turk, for the army of Francisco
Vazquez Coronado went the very farthest way round to get there,
since they started from Mexico and went 110 leagues to the west,
and then 100 leagues to the northeast, and 250 to the north, and all
this brought them as far as the ravines where the cows were, and
after travelling 850 leagues they were not more than 400 leagues
distant from Mexico by a direct route. If one desires to go to the
country of Tiguex, so as to turn from there toward the west in
search of the country of India, he ought to follow the road taken by
the army, for there is no other, even if one wished to go by a
different way, because the arm of the sea which reaches into this
coast toward the north does not leave room for any. But what might
be done is to have a fleet and cross this gulf and disembark in the
neighborhood of the Island of Negroes[559]
and enter the country
from there, crossing the mountain chains in search of the country
from which the people at Tiguex came, or other peoples of the same
sort. As for entering from the country of Florida and from the North
Sea, it has already been observed that the many expeditions which
have been undertaken from that side have been unfortunate and not
very successful, because that part of the country is full of bogs and
poisonous fruits, barren, and the very worst country that is warmed
by the sun. But they might disembark after passing the river of the
Holy Spirit, as Don Hernando de Soto did. Nevertheless, despite the
fact that I underwent much labor, I still think that the way I went to
that country is the best. There ought to be river courses, because
the necessary supplies can be carried on these more easily in large
quantities. Horses are the most necessary things in the new
countries, and they frighten the enemy most.... Artillery is also much
feared by those who do not know how to use it. A piece of heavy
artillery would be very good for settlements like those which
Francisco Vazquez Coronado discovered, in order to knock them
down, because he had nothing but some small machines for slinging
and nobody skilful enough to make a catapult or some other
machine which would frighten them, which is very necessary.[560]](https://image.slidesharecdn.com/5748477-250529164254-f6ea82bb/75/Continuous-Api-Management-Making-The-Right-Decisions-In-An-Evolving-Landscape-Mike-Amundsen-74-2048.jpg)
![I say, then, that with what we now know about the trend of the
coast of the South Sea, which has been followed by the ships which
explored the western part, and what is known of the North Sea
toward Norway, the coast of which extends up from Florida, those
who now go to discover the country which Francisco Vasquez
entered, and reach the country of Cibola or of Tiguex, will know the
direction in which they ought to go in order to discover the true
direction of the country which the Marquis of the Valley, Don
Hernando Cortes, tried to find, following the direction of the gulf of
the Firebrand (Tizon) River.[561]
This will suffice for the conclusion of our narrative. Everything else
rests on the powerful Lord of all things, God Omnipotent, who
knows how and when these lands will be discovered and for whom
He has guarded this good fortune.
Laus Deo.
Finished copying, Saturday the 26th of October, 1596, in Seville.](https://image.slidesharecdn.com/5748477-250529164254-f6ea82bb/75/Continuous-Api-Management-Making-The-Right-Decisions-In-An-Evolving-Landscape-Mike-Amundsen-75-2048.jpg)
![Always Mind Your [Developer] Surroundings - API City 2018](https://cdn.slidesharecdn.com/ss_thumbnails/apicity-alwaysmindyourdevelopersurroundings-181004161507-thumbnail.jpg?width=640&height=640&fit=bounds)
Continuous Api Management Making The Right Decisions In An Evolving Landscape Mike Amundsen
- 1. Continuous Api ManagementMaking The Right Decisions In An Evolving Landscape Mike Amundsen download https://ebookbell.com/product/continuous-api-management-making- the-right-decisions-in-an-evolving-landscape-mike- amundsen-11496954 Explore and download more ebooks at ebookbell.com
- 2. Here are somerecommended products that we believe you will be interested in. You can click the link to download. Continuous Api Management Making The Right Decisions In An Evolving Landscape Second Edition 2nd Edition Mehdi Medjaoui https://ebookbell.com/product/continuous-api-management-making-the- right-decisions-in-an-evolving-landscape-second-edition-2nd-edition- mehdi-medjaoui-50917444 Continuous Api Management Making The Right Decisions In An Evolving Landscape 2nd Edition 2nd Mehdi Medjaoui https://ebookbell.com/product/continuous-api-management-making-the- right-decisions-in-an-evolving-landscape-2nd-edition-2nd-mehdi- medjaoui-35158346 Continuous Api Management 2nd Edition Mehdi Medjaoui Erik Wilde Ronnie Mitra Mike Amundsen https://ebookbell.com/product/continuous-api-management-2nd-edition- mehdi-medjaoui-erik-wilde-ronnie-mitra-mike-amundsen-232816376 Apidriven Devops Strategies For Continuous Deployment Chris Wood Vassili Van Der Mersch Kristopher Sandoval Wood https://ebookbell.com/product/apidriven-devops-strategies-for- continuous-deployment-chris-wood-vassili-van-der-mersch-kristopher- sandoval-wood-12269402
- 3. Continuous Time ProcessesFor Finance Switching Selfexciting Fractional And Other Recent Dynamics Donatien Hainaut https://ebookbell.com/product/continuous-time-processes-for-finance- switching-selfexciting-fractional-and-other-recent-dynamics-donatien- hainaut-44888154 Continuous Renal Replacement Procedures In The Intensive Care Unit Understanding And Differentiated Application Daniel Heise https://ebookbell.com/product/continuous-renal-replacement-procedures- in-the-intensive-care-unit-understanding-and-differentiated- application-daniel-heise-45333370 Continuous Functions Volume 2 1st Edition Jacques Simon https://ebookbell.com/product/continuous-functions-volume-2-1st- edition-jacques-simon-46090984 Continuous Delivery And Devops A Quickstart Guide 3rd Paul Swartout https://ebookbell.com/product/continuous-delivery-and-devops-a- quickstart-guide-3rd-paul-swartout-46593152 Continuous Delivery And Devops A Quickstart Guide Start Your Journey To Successful Adoption Of Cd And Devops 3rd Edition 3rd Revised Paul Swartout https://ebookbell.com/product/continuous-delivery-and-devops-a- quickstart-guide-start-your-journey-to-successful-adoption-of-cd-and- devops-3rd-edition-3rd-revised-paul-swartout-46668506
- 5. Mehdi Medjaoui, ErikWilde, Ronnie Mitra & Mike Amundsen Foreword by Kin Lane Continuous API Management MAKING THE RIGHT DECISIONS IN AN EVOLVING LANDSCAPE
- 7. Mehdi Medjaoui, ErikWilde, Ronnie Mitra, and Mike Amundsen Continuous API Management Making the Right Decisions in an Evolving Landscape Boston Farnham Sebastopol Tokyo Beijing Boston Farnham Sebastopol Tokyo Beijing
- 8. 978-1-492-04355-3 [LSI] Continuous API Management byMehdi Medjaoui, Erik Wilde, Ronnie Mitra, and Mike Amundsen Copyright © 2019 Mehdi Medjaoui, Erik Wilde, Ronnie Mitra, and Mike Amundsen. All rights reserved. Printed in the United States of America. Published by O’Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472. O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles (http://oreilly.com/safari). For more information, contact our corporate/insti‐ tutional sales department: 800-998-9938 or [email protected]. Editor: Alicia Young Indexer: WordCo Indexing Services, Inc. Production Editor: Justin Billing Interior Designer: David Futato Copyeditor: Rachel Head Cover Designer: Karen Montgomery Proofreader: James Fraleigh Illustrators: Rebecca Demarest and Ronnie Mitra November 2018: First Edition Revision History for the First Edition 2018-11-14: First Release See http://oreilly.com/catalog/errata.csp?isbn=9781492043553 for release details. The O’Reilly logo is a registered trademark of O’Reilly Media, Inc. Continuous API Management, the cover image, and related trade dress are trademarks of O’Reilly Media, Inc. The views expressed in this work are those of the authors, and do not represent the publisher’s views. While the publisher and the authors have used good faith efforts to ensure that the information and instructions contained in this work are accurate, the publisher and the authors disclaim all responsibility for errors or omissions, including without limitation responsibility for damages resulting from the use of or reliance on this work. Use of the information and instructions contained in this work is at your own risk. If any code samples or other technology this work contains or describes is subject to open source licenses or the intellectual property rights of others, it is your responsibility to ensure that your use thereof complies with such licenses and/or rights.
- 9. To my fellowAPI Academy members who coached me during the book writing, to my fellow partners who helped me to be useful in the industry, to Kin Lane who shared with me his passion for APIs, and to all the API practitioners who shared their API practices with me that inspired this book. To my parents. —Mehdi Medjaoui To all the people on the API Academy team, at CA, and in my life who made this book possible. It’s been quite a ride! —Erik Wilde To Kairav, for helping me write this dedication. —Ronnie Mitra To all the companies that invited us to come share what we’ve learned and, in the process, taught us so much that we had to try to capture it in this book. —Mike Amundsen
- 11. Table of Contents Foreword.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii 1. The Challenge of API Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 What Is API Management? 2 What Is an API? 3 More Than Just the API 4 API Maturity Stages 5 More Than a Single API 5 The Business of APIs 6 Why Is API Management Difficult? 7 Scope 8 Scale 9 Standards 9 Managing the API Landscape 10 Technology 11 Teams 11 Governance 12 Summary 14 2. API Governance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Understanding API Governance 16 Decisions 16 Governing Decisions 17 Governing Complex Systems 18 Governing Decisions 20 Centralization and Decentralization 22 v
- 12. The Elements ofa Decision 27 Decision Mapping 32 Designing Your Governance System 33 Governance Pattern #1: Interface Supervision 35 Governance Pattern #2: Machine-Driven Governance 36 Governance Pattern #3: Collaborative Governance 37 Summary 38 3. The API as a Product. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Design Thinking 40 Matching People’s Needs 41 Viable Business Strategy 41 The Bezos Mandate 42 Applying Design Thinking to APIs 43 Customer Onboarding 44 Time to Wow! 45 Onboarding for Your APIs 46 Developer Experience 48 Knowing Your Audience 49 Making It Safe and Easy 53 Summary 56 4. The Ten Pillars of an API Product. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Introducing the Pillars 57 Strategy 58 Design 62 Documentation 65 Development 68 Testing 71 Deployment 74 Security 77 Monitoring 79 Discovery and Promotion 81 Change Management 84 Summary 85 5. Continuous API Improvement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Changing an API 88 The API Release Lifecycle 88 Changing the Interface Model 90 Changing the Implementation 92 Changing the Instance 93 vi | Table of Contents
- 13. Changing the SupportingAssets 93 Managing Change Continuously 94 Incremental Improvement 94 API Change Velocity 96 Improving API Changeability 98 Effort Costs 98 Opportunity Costs 99 Coupling Costs 100 Summary 101 6. The API Product Lifecycle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Measurements and Milestones 104 OKRs and KPIs 104 Defining an API Objective 106 Identifying Measurable Results 107 The API Product Lifecycle 108 Stage 1: Create 110 Stage 2: Publish 111 Stage 3: Realize 113 Stage 4: Maintain 115 Stage 5: Retire 115 Applying the Product Lifecycle to the Pillars 117 Create 118 Publish 121 Realize 124 Maintain 126 Retire 127 Summary 128 7. API Teams. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 API Roles 130 Business Roles 132 Technical Roles 134 API Teams 136 Teams and API Maturity 136 Scaling Up Your Teams 142 Teams and Roles at Spotify 143 Scaling Your Teams on Paper 144 Culture and Teams 145 Recognizing Conway’s Law 146 Leveraging Dunbar’s Numbers 147 Enabling Alexander’s Cultural Mosaic 149 Table of Contents | vii
- 14. Supporting Experimentation 151 Summary152 8. API Landscapes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 API Archaeology 157 API Management at Scale 158 The Platform Principle 160 Principles, Protocols, and Patterns 161 API Landscapes as Language Landscapes 164 API the APIs 165 Understanding the Landscape 167 The Eight Vs of API Landscapes 168 Variety 169 Vocabulary 170 Volume 174 Velocity 175 Vulnerability 176 Visibility 177 Versioning 178 Volatility 180 Summary 181 9. API Landscape Journey. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 Structuring Guidance in the API Landscape 184 The Lifecycle of Guidance in the API Landscape 187 The Center for Enablement 188 C4E Team and Context 190 Maturity and the Eight Vs 192 Variety 193 Vocabulary 195 Volume 198 Velocity 200 Vulnerability 202 Visibility 205 Versioning 207 Volatility 209 Summary 211 10. Managing the API Lifecycle in an Evolving Landscape. . . . . . . . . . . . . . . . . . . . . . . . . . . 213 API Products and Lifecycle Pillars 213 API Landscapes 214 Decision Points and Maturity 215 viii | Table of Contents
- 15. Landscape Aspects andAPI Lifecycle Pillars 215 Strategy 217 Design 219 Documentation 221 Development 225 Testing 228 Deployment 233 Security 237 Monitoring 240 Discovery 242 Change Management 246 Summary 249 11. Continuing the Journey. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 Prepare for the Future 252 Start Managing Today 252 Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 Table of Contents | ix
- 17. Foreword APIs are ajourney for any company, organization, institution, or government agency learning to properly manage their digital resources across an ever expanding and evolving competitive digital landscape. This digital transformation that has been building over the last five years is beginning to result in a shift across the API land‐ scape, where companies are beginning to stop asking if they should be doing APIs and have begun seeking more knowledge on how to do APIs properly. Organizations are realizing that there’s more to APIs than just creating them; it’s everything that goes into delivering APIs throughout the entire API lifecycle. The API Academy authors behind Continuous API Management possess a unique understanding of what it takes to move an API from ideation to realization, consistently, at scale, and in a repeatable way—providing the makings for a pretty unique learning opportunity. Most API practitioners operate with a view of the API landscape spanning a single set of APIs. Medjaoui, Wilde, Mitra, and Amundsen possess a unique view of the API landscape at a 250K-foot level, spanning thousands of APIs, multiple industries, and at scale across some of the largest enterprise organizations out there today. I can count the top-tier API talent that exists around the globe on both my hands, and Medjaoui, Wilde, Mitra, and Amundsen are always first to be counted on my right hand. These authors bring a wealth of experience to the table when it comes to understanding what you need to move APIs from inception to design, from develop‐ ment to production, and back again. There just isn’t another team of API experts out there who have the scope and the breadth of API knowledge that this team possesses, making this destined to become that tattered O’Reilly book that lives within reach on the corner of your desk—something you read again and again. I’ve read numerous books on the technical aspects of creating APIs; books about Hypermedia and everything you need to know about REST, and how to deliver on this vision in a variety of programming languages and platforms. This is the first API book that I’ve read that holistically approaches the delivery of APIs from start to fin‐ ish, addressing not only the technological details but also the critical business ele‐ ments of operating APIs—which also includes the critical human side of API Foreword | xi
- 18. education, realization, andactivation across large enterprise organizations. The book methodically lays out the essential building blocks any enterprise API architect will need to deliver reliable, secure, and consistent APIs at scale; it will help any API team quantify their operations and think more critically about how APIs can be improved upon and evolved, while also establishing and refining a structured yet agile approach to delivering APIs in a standardized way across teams. After putting down this book, I felt I had a refreshed look at the modern API lifecycle —but more importantly, I was left with a wealth of ideas about how I actually quan‐ tify and measure my API operations, and the API lifecycle strategy I am using to manage my operations. Even with my knowledge of the space, this book forced me to look at the landscape in some important new ways. I walked away saturated with information that reenforced somewhat I already knew, but also shifted and moved around some of what I thought I knew, forcing me to evolve in some of my existing practices. For me, this is what the API journey is all about: continually being chal‐ lenged, learning, planning, executing, measuring, and repeating until you find the desired results. Continuous API Management reflects this reality of delivering APIs, providing us with a reusable guide to the technology, business, and politics of doing APIs at scale within the enterprise. Don’t just read this book once. Read it, then go out and execute on your vision. Evolve your API strategy, and define a version of the API lifecycle that is all your own, taking what you’ve learned from Medjaoui, Wilde, Mitra, and Amundsen and putting it to work. However, every once in a while, pick this book up again and give it another read. I guarantee there will be little nuggets throughout the book that you’ll rediscover and see in a new light each time you work through it; something that will build and improve your understanding of what is happening across the API land‐ scape, and help you more confidently participate (or lead) when it comes to doing business with APIs across the expanding online economy. — Kin Lane, The API Evangelist xii | Foreword
- 19. Preface As society andbusiness have grown increasingly digital in nature, the demand for connected software has exploded. In turn, the application programming interface (API) has emerged as an important resource for modern organizations because it facilitates software connections. But managing these APIs effectively has proven a new challenge. Getting the best value from your APIs means learning how to manage their design, development, deployment, growth, quality, and security while dealing with the complicating factors of context, time, and scale. Who Should Read This Book If you are just starting to build an API program and want to understand the work ahead of you, or if you already have APIs but want to learn how to manage them bet‐ ter, then this is the book for you. In this book, we’ve tried to build an API management framework that can be applied to more than one context. In these pages you’ll find guidance that will help you to manage a single API that you want to share with developers around the world, as well as advice for building a complex set of APIs in a microservice architecture designed only for internal developers—and everything in between. We’ve also written this book to be as technologically neutral as possible. The advice and analysis we provide is applicable to any API-based architecture, including HTTP CRUD, REST, GraphQL, and event-driven styles of interaction. This is a book for anyone who wants to improve the decisions being made about their APIs. What’s in This Book This book contains our collective knowledge from many years spent designing, devel‐ oping, and improving APIs—both our own and others’. We’ve distilled all that expe‐ rience into this book. We’ve identified two core factors for effective API development: adopting a product perspective and implementing the right kind of Preface | xiii
- 20. team. We’ve alsoidentified three essential factors for managing that work: gover‐ nance, product maturity, and landscape design. These five elements of API management form a foundation on which you can build a successful API management program. In this book, we introduce each of these topics and provide you with guidance on how to shape them to fit your own organizational context. The Outline We’ve organized the book so that the scope of management concerns grows as you progress through the chapters. We start by introducing the foundational concepts of decision-based governance and the API as a product. This is followed by a tour of all the work that must be managed when building an API product. From this simple view of a single API, we then add the aspect of time as we dive into what it means to change an API and how the maturity of the API impacts those change decisions. This is followed by an exploration of the teams and people who do that change work. Finally in the last half of the book we tackle the complexities of scale and the challenges of managing a landscape of API products. Here is a short summary of what you’ll find in each chapter: Chapter 1 introduces the API management domain and explains why it’s so difficult to manage APIs effectively. Chapter 2 explores governance from the perspective of decision-based work—a foun‐ dational concept for API management. Chapter 3 establishes the API-as-a-Product perspective and why it’s an essential part of any API strategy. Chapter 4 outlines the ten essential pillars of work in the API product domain. These pillars form a set of decision-making tasks that must be managed. Chapter 5 provides insight into what it means to change an API continuously. It introduces the need to adopt a continuous change mentatlity and provides an under‐ standing of the different types of API changes (and their impacts) that you’ll encounter. Chapter 6 introduces the API product lifecycle, a framework that will help you man‐ age API work across the ten pillars over the life of an API product. Chapter 7 addresses the people element of an API management system by exploring the typical roles, responsibilities, and design patterns for an API team over the life of an API product. xiv | Preface
- 21. Chapter 8 addsthe perspective of scale to the problem of managing APIs. It introdu‐ ces the eight Vs—variety, vocabulary, volume, velocity, vulnerability, visibility, ver‐ sioning, and volatility—that must be addressed when multiple APIs are changing at the same time. Chapter 9 outlines a continuous landscape design approach for managing API changes continuously and at scale. Chapter 10 maps the landscape perspective back to the API-as-a-Product perspective and identifies how API work changes when the landscape evolves around it. Chapter 11 ties together the story of API management that has emerged and provides advice on preparing for the future and starting your journey today. What’s Not in This Book The scope of API management is big, and there is a massive amount of variation in contexts, platforms, and protocols. Given the constraints of time and space when writing a book, it was impossible for us to address all the specific implementation practices of API work. This book isn’t a guide for designing a REST API, or for pick‐ ing a security gateway product. If you are looking for a prescriptive guide to writing API code or designing an HTTP API, this isn’t the right book for you. While we do have examples that talk about specific practices, this isn’t an API imple‐ mentation–focused book (the good news is there are plenty of books, blogs, and vid‐ eos available already to help you fill that need). Instead, this book tackles a problem that is rarely addressed: how to effectively manage the work of building APIs within a complex, continuously changing organizational system. Conventions Used in This Book The following typographical conventions are used in this book: Italic Indicates new terms, URLs, email addresses, filenames, and file extensions. Constant width Indicates program elements such as variable or function names, data types, state‐ ments, and keywords. Constant width italic Shows text that should be replaced with user-supplied values or by values deter‐ mined by context. Preface | xv
- 22. This element signifiesa tip or suggestion. This element signifies a general note. This element indicates a warning or caution. Safari® Books Online Safari Books Online is an on-demand digital library that deliv‐ ers expert content in both book and video form from the world’s leading authors in technology and business. Technology professionals, software developers, web designers, and business and crea‐ tive professionals use Safari Books Online as their primary resource for research, problem solving, learning, and certification training. Safari Books Online offers a range of plans and pricing for enterprise, government, education, and individuals. Members have access to thousands of books, training videos, and prepublication manuscripts in one fully searchable database from publishers like O’Reilly Media, Prentice Hall Professional, Addison-Wesley Professional, Microsoft Press, Sams, Que, Peachpit Press, Focal Press, Cisco Press, John Wiley & Sons, Syngress, Morgan Kaufmann, IBM Redbooks, Packt, Adobe Press, FT Press, Apress, Manning, New Riders, McGraw-Hill, Jones & Bartlett, Course Technology, and hundreds more. For more information about Safari Books Online, please visit us online. How to Contact Us Please address comments and questions concerning this book to the publisher : O’Reilly Media, Inc. 1005 Gravenstein Highway North xvi | Preface
- 23. Sebastopol, CA 95472 800-998-9938(in the United States or Canada) 707-829-0515 (international or local) 707-829-0104 (fax) To comment or ask technical questions about this book, send email to bookques‐ [email protected]. For more information about our books, courses, conferences, and news, see our web‐ site at http://www.oreilly.com. Find us on Facebook: http://facebook.com/oreilly Follow us on Twitter: http://twitter.com/oreillymedia Watch us on YouTube: http://www.youtube.com/oreillymedia Acknowledgments We have lots of people to thank for all the help and support we received over the last year as we worked through early outlines, drafts, and edits of this book. First, thanks to all the people we interviewed and consulted with, and who attended our work‐ shops. We got great feedback and excellent advice from each and every encounter. Additional thanks go to the folks at CA Technologies who supported us over the years and helped make all those workshops and onsite visits possible. Special thanks to the people who read through our early drafts and helped us shape the final book you see here. Matt McLarty, James Higginbotham, and Chris Wood all took time out of their own busy schedules to read and review our work and point out places where it could be better. Finally, our big thanks to the team at O’Reilly Media. Thanks to Alicia Young, Justin Billing, and all the folks at O’Reilly for all their efforts to turn our initial ideas into the book you see before you now. Preface | xvii
- 25. CHAPTER 1 The Challengeof API Management Management is, above all, a practice where art, science, and craft meet —Henry Mintzberg A survey from Coleman Parkes released in 2017 shows that almost 9 in 10 global enterprises have some form of API program. This same survey shows that these com‐ panies are seeing a wide variety of benefits from their API programs, including an average increase in speed-to-market of around 18%. However, only about 50% of these same companies say they have an advanced API management program. This points to a key gap in many enterprise-level API programs: the distance between the operational APIs that represent key contributions to revenue and the management skills and infrastructure needed to support these revenue-producing APIs. It is this gap that this book hopes to address. The good news is there are many companies out there successfully managing their API programs. The not-so-good news is that their experience and expertise is not easily shared or commonly available. There are several reasons for this. Most of the time, organizations that are doing well in their API management programs are sim‐ ply too busy to share their experiences with others. In a few cases, we’ve talked to companies that are very careful about how much of their API management expertise they share with the outside world; they are convinced API skills are a competitive advantage and are slow to make their findings public. Finally, even when companies share their experience at public conferences and through articles and blog posts, the information they share is usually company-specific and difficult to translate to a wide range of organizations’ API programs. This book is an attempt to tackle that last problem—translating company-specific examples into shared experience all organizations can use. To that end, we have vis‐ ited with dozens of companies, interviewed many API technologists, and tried to find the common threads between the examples companies have shared with us and with 1
- 26. the public. Thereare a small handful of themes that run through this book that we’ll share here in this introductory chapter. A key challenge to identify right up front is sorting out just what people mean when they talk about APIs. First, the term “API” can be applied to just the interface (e.g., an HTTP request URL and JSON response). It can also refer to the code and deployment elements needed to place an accessible service into production (e.g., the customerOn Boarding API). Finally, we sometimes use “API” to refer to a single instance of a run‐ ning API (e.g., the customerOnBoarding API running in the AWS cloud vs. the customerOnBoarding API running on the Azure cloud). Another important challenge in managing APIs is the difference between the work of designing, building, and releasing a single API and supporting and managing many APIs—what we call an API landscape. We will spend a good deal of time in this book on both ends of this spectrum. Concepts like API-as-a-Product (AaaP) and the skills needed to create and maintain APIs (what we call API pillars) are examples of dealing with the challenges of a single API. We will also talk about the role of API maturity models and the work of dealing with change over time as important aspects of man‐ aging an API. The other end of that spectrum is the work of managing the API landscape. Your landscape is the collection of APIs from all business domains, running on all plat‐ forms, managed by all the API teams in your company. There are several aspects to this landscape challenges, including how scale and scope change the way APIs are designed and implemented as well as how large ecosystems can introduce added vol‐ atility and vulnerability just because of their size. Finally, we touch on the process of decision making when managing your API eco‐ system. In our experience this is the key to creating a successful governance plan for your API programs. It turns out the way you make decisions needs to change along with your landscape; holding on to old governance models can limit your API pro‐ gram’s success and even introduce more risk into your existing APIs. Before we dive into the details on how you can learn to deal with both challenges— your individual APIs and your API landscape—let’s take a look at two important questions: what is API management, and why is it so hard? What Is API Management? As mentioned, API management involves more than just governing the design, implementation, and release of APIs. It also includes the management of an API eco‐ system, the distribution of decisions within your organization, and even the process of migrating existing APIs into your growing API landscape. In this section, we’ll spend time on each of these concepts—but first, a short explanation of what we mean by “API.” 2 | Chapter 1: The Challenge of API Management
- 27. What Is anAPI? Sometimes when people use the term “API” they are talking about not only the inter‐ face, but also the functionality—the code behind the interface. For example, someone might say, “We need to release the updated Customer API soon so that other teams can start using the new search functionality we implemented.” Other times, people may use the term to refer only to the details of the interface itself. For example, some‐ one on your team might say, “What I’d like to do is design a new JSON API for the existing SOAP services that support our customer onboarding workflow.” Both are correct, of course—and it seems pretty clear what is meant in both cases—but it can be confusing at times. To try to clear up the distinction and make it easier for us to talk about both the interface and the functionality, we are going to introduce some additional terms: interface, implementation, and instance. Interface, implementation, and instance The acronym API stands for application programming interface. We use interfaces to gain access to something running “behind” the API. For example, you may have an API that exposes tasks for managing user accounts. This interface might allow devel‐ opers to: • Onboard a new account. • Edit an existing account profile. • Change the status of (suspend or activate) an account. This interface is usually expressed using shared protocols such as HTTP, Thrift, TCP/IP, etc. and relies on standardized formats like JSON, XML, or HTML. But that’s just the interface. Something else actually needs to perform the requested tasks. That something else is what we’ll be referring to as the Implementation. The implementation is the part that provides the actual functionality. Often this imple‐ mentation is written in a programming language such as Java, C#, Ruby, or Python. Continuing with the example of the user account, a UserManagement implementation could contain the ability to create, add, edit, and remove users. This functionality could then be exposed using the interface mentioned previously. What Is API Management? | 3
- 28. Decoupling the Interfacefrom the Implementation Note that the functionality of the implementation described is a simple set of actions using the Create, Read, Update, Delete (CRUD) pattern, but the interface we described has three actions (OnboardAccount, EditAccount, and ChangeAccountStatus). This seeming “mismatch” between the implementation and the interface is common and can be powerful; it decouples the exact implemen‐ tation of each service from the interface used to access that service, making it easier to change over time without disruption. The third term in our list is instance. An API instance is a combination of the inter‐ face and the implementation. This is a handy way to talk about the actual running API that has been released into production. We manage instances using metrics to make sure they are healthy. We register and document instances in order to make it easy for developers to find and use the API to solve real-world problems. And we secure the instance to make sure that only authorized users are able to execute the actions and read/write the data needed to make those actions possible. Figure 1-1 clarifies the relationship between the three elements. Often in this book, when we write “API” we’re talking about the instance of the API: a fully operational combination of interface and implementation. In cases where we want to highlight just the interface or only the implementation, we’ll call that out in the text. Figure 1-1. Three API elements More Than Just the API The API itself—the technical details of interface and implementation—is just part of the story, too. The traditional elements of design-build-deploy are, of course, critical to the life of your APIs. But actually managing APIs also means testing them, docu‐ menting them, and publishing them to a portal so that the right audience (internal 4 | Chapter 1: The Challenge of API Management
- 29. 1 At musicstreaming service, Spotify, they call these cross-cutting groups “guilds.” See “Scaling Up Your Teams” on page 142 for more on this topic. developers, partners, third-party anonymous app developers, etc.) can find and learn how to use them properly. You also need to secure your APIs, monitor them at run‐ time, and maintain them (including handling changes) over their lifetime. All these additional elements of an API are what we call API pillars: elements that all APIs need and all API program managers need to deal with. We’ll dig into pillars in Chap‐ ter 4, where we walk through the list of ten key practices vital to creating and main‐ taining healthy APIs. The good news about these practice areas is that they transcend any single API. For example, the skill of documenting APIs well is transferable from one API team to the next. The same goes for learning proper testing skills, security patterns, and so forth. That also means that even when you have separate teams for each API domain (sales team, product team, backoffice team, etc.), you also have “cross-cutting” interests that bind people within teams to other people in other teams.1 And this is another important aspect of managing APIs—enabling and engineering the teams that build them. We talk more about how this works in different organizations in Chapter 7. API Maturity Stages Knowing and understanding the API pillars is not the entire picture, either. Each API in your program goes through its own “lifecycle”—a series of predictable and useful stages. Knowing where you are in the API journey can help you determine how much time and resources to invest in the API at the moment. Understanding how APIs mature allows you to recognize the same stages for a wide range of APIs and helps you prepare for and respond to the varying requirements of time and energy at each stage. On the surface, it makes sense to consider that all of the API pillars need to be dealt with when designing, building, and releasing your APIs. But reality is different. Often, for early-stage APIs it is most important to focus on the design and build aspects and reduce efforts on documentation, for example. At other stages (e.g., once a prototype is in the hands of beta testers), spending more time on monitoring the use of the API and securing it against misuse is more important. Understanding maturity stages will help you determine how to allocate limited resources for maxi‐ mum effect. We’ll walk you through this process in Chapter 6. More Than a Single API As many readers may already know, things change when you start managing a lot of APIs. We have customers with thousands of APIs that they need to build, monitor, What Is API Management? | 5
- 30. and manage overtime. In this situation, you focus less on the details of how a single API is implemented and more on the details of how these APIs coexist in an ever- growing, dynamic ecosystem. As mentioned earlier, we call this ecosystem the API landscape, and we devote several chapters to this concept in the second half of the book. Much of the challenge here is how to assure some level of consistency without caus‐ ing bottlenecks and slowdowns due to centralized management and review of all the API details. This is usually accomplished by extending responsibility for those details to the individual API teams and focusing central management/governance efforts on normalizing the way APIs interact with each other, ensuring that there is a core set of shared services or infrastructure (security, monitoring, etc.) in place and available for all API teams, and generally providing guidance and coaching to more autonomous teams. That is, it’s often necessary to move away from the usual centralized command-and-control model. One of the challenges when working toward distributing decision making and autonomy deeper in the organization is that it can be easy for those higher up in the organization to lose visibility into important activities happening at the team level. Whereas in the past a team might have had to ask permission to take an action, com‐ panies that extend additional autonomy to the individual teams will encourage them to act without waiting for upper-level review and permission. Most of the challenges of managing a landscape of APIs have to do with scale and scope. It turns out that as your API program grows, it doesn’t just get bigger; it also changes in shape. We’ll discuss this in more detail later in this chapter (see “Why Is API Management Difficult?” on page 7). The Business of APIs Beyond the details of creating APIs and managing them in a landscape, it is impor‐ tant to keep in mind that all this work is meant to support business goals and objec‐ tives. APIs are more than the technical details of JSON or XML, synchronous or asynchronous, etc. They are a way to connect business units together, to expose important functionality and knowledge in a way that helps the company be effective. APIs are often a way to unlock value that is already there in the organization, for example through creating new applications, enabling new revenue streams, and ini‐ tiating new business. This kind of thinking focuses more on the needs of API consumers instead of those producing and publishing the APIs. This consumer-centric approach is commonly referred to as “Jobs to Be Done,” or JTBD. It was introduced by Harvard Business School’s Clayton Christensen, whose books The Innovator’s Dilemma and The Inno‐ vator’s Solution (Harvard Business Review Press) explore the power of this approach in depth. For the purposes of launching and managing a successful API program, it 6 | Chapter 1: The Challenge of API Management
- 31. serves as aclear reminder that APIs exist to solve business problems. In our experi‐ ence, companies that are good at applying APIs to business problems treat their APIs as products that are meant to “get a job done” in the same sense that Christensen’s JTBD framework solves consumer problems. One way an API program can help the business is by creating a flexible set of “tools” (the APIs) to build new solutions without incurring a high cost. For example, if you have an OnlineSales API that allows key partners to manage and track their sales activity and a MarketingPromotions API—that allows the marketing team to design and track product promotional campaigns, you have an opportunity to create a new partner solution: the SalesAndPromotions tracking application. Another way APIs can contribute to the business is by making it easy to access important customer or market data that can be correlated to emerging trends or unique behaviors in new customer segments. By making this data safely and easily available (properly anonymized and filtered), APIs may enable your business to dis‐ cover new opportunities, realize new products/services, or even start new initiatives at a reduced cost and faster time to market. We cover this important aspect of AaaP in Chapter 3. Why Is API Management Difficult? As we mentioned at the beginning of this chapter, while most companies have already launched an API program, only about 50% consider themselves to be doing a good job managing their APIs. What’s going on here? What are the challenges, and how can you help your company overcome them? As we visit with companies all over the world, talking about API lifecycle manage‐ ment, a few basic themes emerge: Scope Just what is it that central software architecture teams should be focusing upon when governing APIs over time? Scale Often, what works when companies are just starting out on their API journey doesn’t scale as the program grows from a few small teams to a global initiative. Standards What we find is that, as programs mature, management and governance efforts need to move from detailed advice on API design and implementation to more general standardization of the API landscape, freeing teams to make more of their own decisions at a detailed level. Why Is API Management Difficult? | 7
- 32. Essentially, it isthe continued balance of these three elements—scope, scale, and standards—that powers a healthy, growing API management program. For this rea‐ son, it is worth digging into these a bit more. Scope One of the big challenges of operating a healthy API management program is achiev‐ ing the proper level of central control. And, to make it even more challenging, the proper level changes as the program matures. Early in the program, it makes sense to focus on the details of designing the API directly. In cases where APIs are in their infancy, these design details might come directly from the team creating the API—they look at existing programs “in the wild,” adopt tooling and libraries that make sense for the style of API they plan to create, and go ahead and implement that API. In this “early-stage” API program everything is new; all problems are encountered (and solved) for the first time. These initial experiences often end up being chroni‐ cled as the company’s “API Best Practices” or company guidelines, etc. And they make sense for a small team working on a few APIs for the very first time. However, those initial guidelines may turn out to be incomplete. As the number of teams working on APIs at the company grows, so does the variety of styles, experiences, and points of view. It gets more difficult to maintain consis‐ tency across all the teams—and not just because some teams are not adhering to the published company guidelines. It may be that a new team is working with a different set of off-the-shelf products that constrain their ability to follow the initial guidelines. Maybe they don’t work in an event-streaming environment and are supporting XML- based call-and-response-style APIs. They need guidance, of course, but it needs to fit their domain, their customers’ needs. There are certainly some guidelines that all teams need to share, but that guidance needs to fit their problem domains as well as their API customers’ needs. As your community widens, your diversity increases, and it is essential that you don’t make the mistake of trying to eliminate that diversity. This is where your lever of control needs to move from giving orders (e.g., “All APIs MUST use the following URL pat‐ terns…”) to giving guidance (e.g., “APIs running over HTTP SHOULD use one of the following URL templates…”). In other words, as your program’s scope expands, your collection of guidelines needs to expand appropriately. This is especially important for global enterprises where local culture, language, and history play an important role in the way teams think, create, and solve problems. And that leads us to the next key element: scale. 8 | Chapter 1: The Challenge of API Management
- 33. Scale Another big challengefor creating and maintaining a healthy API management pro‐ gram is dealing with changes in scale over time. As we discussed in the previous sec‐ tion, growing the number of teams and the number of APIs created by those teams can be a challenge. The processes needed to monitor and manage the APIs at runtime will also change as the system matures. The tooling needed to keep track of a handful of APIs all built by the same team in a single physical location is very different from the tooling needed to keep track of hundreds or thousands of API entry points scat‐ tered across multiple time zones and countries. In this book we talk about this aspect of API management as the “landscape.” As your program scales up, you need to be able to keep an eye on lots of processes by lots of teams in lots of locations. You’ll rely more on monitoring runtime behavior to get a sense of how healthy your system is at any one moment. In the second part of this book (starting with Chapter 8) we’ll explore how the notion of managing the API landscape can help you figure out which elements deserve your focus and what tools and processes can help you keep a handle on your growing API platform. API landscapes pose a new set of challenges. The processes you use to design, imple‐ ment, and maintain a single API are not always the same when you need to scale your ecosystem. This is basically a game of numbers: the more APIs you have in your sys‐ tem, the more likely it is that they will interact with each other, and that increases the likelihood that some of those interactions will result in unexpected behavior (or “errors”). This is the way large systems work—there are more interactions and more unexpected results. Trying to remove these unexpected results only gets you part of the way. You can’t eliminate all the bugs. And that leads to the third challenge most growing API programs encounter: how can you reduce unexpected changes by applying the appropriate level of standards within your API program? Standards One of the key shifts that happen when you begin managing at the landscape level instead of the API level is in the power of standards in providing consistent guidance for teams designing, implementing, and deploying APIs in your organization. As groups grow larger—including the group of teams responsible for your organiza‐ tion’s APIs—there is a coordination cost that is incurred (see “Decisions” on page 16). The growing scale requires a change in scope. And a key way to deal with this chal‐ lenge is to rely more on general standards instead of specific design constraints. For example, one of the reasons the World Wide Web has been able to continue to function well since its inception in 1990 is that its designers decided early on to rely on general standards that apply to all types of software platforms and languages Why Is API Management Difficult? | 9
- 34. instead of creatingtightly focused implementation guidance based on any single lan‐ guage or framework. This allows creative teams to invent new languages, architecture patterns, and even runtime frameworks without breaking any existing implementa‐ tions. A common thread that runs through the long-lived standards that have helped the web continue to be successful is the focus on standardizing the interaction between components and systems. Instead of standardizing the way components are imple‐ mented internally (e.g., use this library, this data model, etc.), web standards aim to make it easy for parties to understand each other over the wire. Similarly, as your API program grows to a more mature level, the guidance you provide to your API com‐ munity needs to focus more on general interaction standards instead of specific implementation details. This can be a tough transition to make, but it is essential to moving up the ladder to a healthy API landscape where it is possible for teams to build APIs that can easily interact with both the existing and the future APIs in your system. Managing the API Landscape As mentioned at the start of this chapter, there are two key challenges in the API management space: managing the life of a single API and managing the landscape of all the APIs. In our visits to many companies and our research into API management in general, we find many versions of the “managing a single API” story. There are lots of “lifecycles” and “maturity models” out there that provide solid advice on identify‐ ing and mitigating the challenges of designing, building, and deploying an API. But we have not found much in the way of guidance when it comes to an ecosystem (we call it a landscape) of APIs. Landscapes have their own challenges; their own behaviors and tendencies. What you need to take into account when you design a single API is not the same as what you must consider when you have to support tens, hundreds, or even thousands of APIs. There are new challenges at scale that happen in an ecosystem—things that don’t happen for a single instance or implementation of an API. We dive deep into the API landscape later in the book, but we want to point out three ways in which API land‐ scapes present unique challenges for API management here at the start of the book: • Scaling technology • Scaling teams • Scaling governance Let’s take a moment to review each of these aspects of API management with regard to landscapes. 10 | Chapter 1: The Challenge of API Management
- 35. Technology When you arefirst starting your API program, there are a series of technical deci‐ sions to make that will affect all your APIs. The fact that “all” your APIs is just a small set at this point is not important. What is important is that you have a consistent set of tools and technologies that you can rely upon as you build out your initial API program. As you’ll see when we get into the details of the API lifecycle (Chapter 6) and API maturity, API programs are not cheap, and you need to carefully monitor your investments of time and energy into activities that will have a high impact on your API’s success without risking lots of capital too early in the process. This usually means selecting and supporting a small set of tools and providing a very clear, often detailed set of guidance documents to help your API teams design and build APIs that both solve your business problems and work well together. In other words, you can gain early wins by limiting your technical scope. This works well at the start, for all the reasons we’ve mentioned. However, as your program scales up in volume (see “Volume” on page 174) and its scope widens (e.g., more teams building more APIs to serve more business domains in more locations, etc.). the challenges also change. As you grow your API program, relying on a limited set of tools and technologies can become one of the key things that slow you down. While at the beginning, when you had a small set of teams, limiting choices made things move faster, placing limits on a large set of teams is a costly and risky enter‐ prise. This is especially true if you start to add teams in geographically distant loca‐ tions and/or when you embrace new business units or acquire new companies to add to your API landscape. At this point variety (see “Variety” on page 169) becomes a much more important success driver for your ecosystem. So, an important part of managing technology for API landscapes is identifying when the landscape has grown large enough to start increasing the variety of technologies instead of restricting them. Some of this has to do with the realities of existing imple‐ mentations. If your API landscape needs to support your organization’s existing SOAP-over-TCP/IP services, you can’t require all these services to use the same URL guidance you created for your greenfield CRUD-over-HTTP APIs. The same goes for creating services for new event-driven Angular implementations or the legacy remote procedure call (RPC) implementations. A wider scope means more technological variety in your landscape. Teams Technology is not the only aspect of API management that surfaces a new set of chal‐ lenges as the program grows. The makeup of the teams themselves needs to adjust as the landscape changes, too. Again, at the start of your API program, you can operate with just a few committed individuals doing—for the most part—everything. This is when you hear names like “full-stack developer,” or “MEAN” [MongoDB, Express.js, Managing the API Landscape | 11
- 36. Angular.js, Node.js] developeror some other variation on the idea of a single devel‐ oper that has skills for all aspects of your API program. You also may hear lots of talk about “startup teams” or “self-contained teams.” It all boils down to having all the skills you need in one team. This makes sense when your APIs are few and they all are designed and implemented using the same set of tools (see “Technology” on page 11). But as the scale and scope of your API program grows, the number of skills required to build and maintain your APIs gross, too. You can no longer expect each API team to consist of a set number of people with skills in design, database, backend, frontend, testing, and deployment. You might have a team whose job is to design and build a data-centric dashboard interface used by a wide range of other teams. Their skills may, for example, need to cover all the data formats used and tools needed to collect that data. Or you might have a team whose primary job is to build mobile apps that use a single technology like GraphQL or some other query-centric library. As technological variety grows, your teams may need to become more specialized. We’ll have a chance to explore this in detail later, in Chapter 7. Another way in which teams will need to change as your API landscape grows is the way in which they participate in day-to-day decision-making processes. When you have a small number of teams and their experience is not very deep, it can make sense to centralize the decision making to a single, guiding group. In large organizations this is often the Enterprise Architecture group or something with a similar name. This works at smaller scales and scopes but becomes a big problem as your ecosystem becomes less homogeneous and more wide-ranging. As tech gets more involved, a single team is unlikely to be able to keep up with the details of each tool and frame‐ work. And as you add more and more teams, decision making itself needs to be dis‐ tributed; a central committee rarely understands the realities of the day-to-day operations in a global enterprise. The solution is to break down the decision-making process into what we call decision elements (see “The Elements of a Decision” on page 27) and distribute those elements to the proper levels within your company. A growing ecosystem means teams need to become more specialized on a technical level and more responsible at the decision- making level. Governance The last area that we want to touch on in regards to the challenge of API landscapes is the general approach to governance of your API program. Again, as in other cases mentioned here, it is our observation that the role and levers of governance will change as your ecosystem grows. New challenges appear, and old methods are not as effective as they were in the past. In fact, especially at the enterprise level, sticking to old governance models can slow or even stall the success of your APIs. 12 | Chapter 1: The Challenge of API Management
- 37. Just as inany area of leadership, when the scope and scale are limited, an approach based on providing direct guidance can be the most effective. This is often true not just for small teams, but also for new teams. When there is not a lot of operating experience, the quickest way to success is to provide that experience in the form of detailed guidance and/or process documents. For example, we find early API pro‐ gram governance often takes the form of multipage process documents that explain specific tasks: how to design the URLs for an API, or which names are valid for URLs, or where the version number must appear in an HTTP header. Providing clear guide‐ lines with few options makes it hard for developers to stray from the approved way of implementing your APIs. But again, as your program grows, as you add more teams and support more business domains, the sheer size and scope of the community begin to make it very difficult to maintain a single guidance document that applies to all teams. And while it is possi‐ ble to “farm out” the job of writing and maintaining detailed process documents for the entire enterprise, it is usually not a good idea anyway—as we mentioned in “Technology” on page 11, technology variety becomes a strength in a large ecosys‐ tem, and attempting to rein it in at the enterprise governance level can slow your pro‐ gram’s progress. That’s why as your API landscape expands, your governance documents need to change in tone from offering direct process instructions toward providing general principles. For example, instead of writing up details on what constitutes a valid URL for your company, it is better to point developers to the Internet Engineering Task Force’s guidelines on URI design and ownership (RFC 7320) and provide general guidance on how to apply this public standard within your organization. Another great example of this kind of principled guidance can be found in most UI/UX guide‐ lines, such as the “10 Usability Heuristics for User Interface Design” from the Nielsen Norman Group. These kinds of documents provide lots of options and rationales for using one UI pattern over another. They offer developers and designers guidance on why and when to use something instead of simply setting requirements for them to follow. Finally, for very large organizations, and especially companies that operate in multi‐ ple locations and time zones, governance needs to move from distributing principles to collecting advice. This essentially reverses the typical central governance model. Instead of telling teams what to do, the primary role of the central governance com‐ mittee becomes to collect experience information from the field, find correlations, and echo back guidance that reflects “best practice” within the wider organization. So, as your API landscape grows, your API governance model needs to move from providing direct advice to presenting general principles to collecting and sharing practices from experienced teams within your company. As we’ll see in Chapter 2, Managing the API Landscape | 13
- 38. there are ahandful of principles and practices you can leverage in order to create the kind of governance model that works for your company. Summary In this opening chapter, we touched on a number of important aspects of API man‐ agement that appear within this book. We acknowledged that while APIs continue to be a driving force, barely 50% of companies surveyed are confident of their ability to properly manage these APIs. We also clarified the many uses of the term “API” and how these different uses may make it harder to provide a consistent governance model for your program. And, most importantly, we introduced the notion that managing “an API” is very dif‐ ferent from managing your “API landscape.” In the first case, you can rely on API-as- a-Product, API lifecycle, and API maturity models. Change management for APIs is also very much focused on this “an API” way of thinking. But this is just part of the story. Next, we discussed managing your API landscape—the entire API ecosystem within your organization. Managing a growing landscape of APIs takes a different set of skills and metrics; skills in dealing with variety, volume, volatility, vulnerability, and several other aspects. In fact, these landscape aspects all affect the API lifecycle, and we’ll review them in detail later in this book. Finally, we pointed out that even the way you make your decisions about your API program will need to change over time. As your system grows, you need to distribute decision making just as you distribute IT elements like data storage, computational power, security, and other parts of your company’s infrastructure. With this introduction as a background, let’s start by focusing on the notion of gover‐ nance and how you can use decision-making and the distribution of decisions as a primary element in your overall API management approach. 14 | Chapter 1: The Challenge of API Management
- 39. CHAPTER 2 API Governance Hey,a rule is a rule, and let’s face it, without rules there’s chaos. —Cosmo Kramer Governance isn’t the kind of thing people get excited about. It’s also a topic that car‐ ries a bit of emotional baggage. After all, few people want to be governed and most people have had bad experiences with poorly designed governance policies and non- sensical rules. Bad governance (like bad design) makes life harder. But in our experi‐ ence, it’s difficult to talk about API management without addressing it. In fact, we’ll go as far as saying that it’s impossible to manage your APIs without gov‐ erning them. Sometimes, API governance happens in a company, but the term “governance” is never used. That’s perfectly fine. Names matter, and in some organizations gover‐ nance implies a desire to be highly centralized and authoritative. That can run counter to a culture that embraces decentralization and worker empowerment, so it makes sense that governance is a bad word in those kinds of places. No matter what it’s called, even in this type of decentralized work culture, some form of decision gov‐ ernance is taking place—but it will probably look radically different from the gover‐ nance system at a more traditional, top-down organization. The question “Should you govern your APIs?” isn’t very interesting, because in our opinion, the answer is always yes. Instead, ask yourself: “Which decisions need to be governed?” and “Where should that governance happen?” Deciding on the answers to these types of questions is the work of designing a governance system. Different styles of governance can produce vastly different working cultures, productivity rates, product quality, and strategic value. You’ll need to design a system that works for you. Our goal in this chapter is to give you the building blocks to do that. 15
- 40. We’ll start byexploring the three foundational elements of good API governance: decisions, governance, and complexity. Armed with this understanding, we’ll take a closer look at how decisions can actually be distributed in your company and how that impacts the work you do. That means taking a closer look at centralization, decentralization, and the elements of what makes a decision. Finally, we’ll take a look at what it means to build a governance system and take a tour of three governance styles. Governance is a core part of API management, and the concepts we introduce in this chapter will be built upon throughout the rest of this book. So, it’s worthwhile to spend some time understanding what API governance really means and how it can help you build a better API management system. Understanding API Governance Technology work is the work of making decisions—lots of decisions, in fact. Some of those decisions are vitally important, while others are trivial. All this decision making is the reason that we can say a technology team’s work is knowledge work. The key skill for a knowledge worker is to make many high-quality decisions, over and over again. That’s a fairly obvious concept, but also one that’s easy to forget when you’re managing APIs. No matter which technologies you introduce, how you design your architecture, or which companies you choose to partner with, it’s the decision-making abilities of everyone involved that dictate the fate of your business. That’s why governance mat‐ ters. You need to shape all of those decisions in a way that helps you achieve your organizational goals. That’s harder to do than it sounds. To give yourself a better chance of success you’ll need a better understanding of the foundational concepts of governance and how they relate to each other. Let’s start by taking a quick look at API decisions. Decisions Your work and the work that many people in your organization perform is primarily the work of making decisions. That’s why governance is so important. If you can make better decisions as a group you can produce better results. But don’t forget that those decisions aren’t just choices about technology—you’ll need to make a broad range of decisions in the API domain. Consider the following list of choices an API team might need to make: 1. Should our API’s URI be /payments or /PaymentCollection? 2. Which cloud provider should we host our API in? 3. We have two customer information APIs—which one do we retire? 16 | Chapter 2: API Governance
- 41. 4. Who’s goingto be on the development team? 5. What should I name this Java variable? From this short list of decisions we can make a few observations. First, API manage‐ ment choices span a wide spectrum of concerns and people—making those choices will require a lot of coordination between people and teams. Second, the individual choices people make have different levels of impact—the choice of a cloud provider is likely to affect your API management strategy much more than the name of a Java variable. Third, small choices can have a big impact at scale—if 10,000 Java variables are named poorly, the maintainability of your API implementations will suffer greatly. All of these choices, spanning multiple domains, being made in coordination and at scale, need to come together to produce the best result. That’s a big and messy job. Later in this chapter we’ll pick this problem apart and give you some guidance for shaping your decision system. But first, let’s take a closer look at what it means to govern these decisions and why governance is so important. Governing Decisions If you’ve ever worked on a small project by yourself, you know that the success or failure of that work relies solely on you. If you make good decisions consistently, you can make something good happen. A single, highly skilled programmer can produce some amazing things. But this way of working doesn’t scale very well. When the thing you produce starts getting used, the demand for more changes and more features grows. That means you need to make many more decisions in a shorter space of time —which means you’ll need more decision makers. Scaling decision making like this requires care. You can’t afford for the quality of your decisions to drop just because there are more people making them. That’s where governance comes in. Governance is the process of managing decision making and decision implementation. Notice that we aren’t saying that governance is about control or authority. Governance isn’t about power. It’s about improving the decision-making quality of your people. In the API domain, high-quality governance means producing APIs that help your organization succeed. You may need some level of control and authority to achieve that, but it’s not the goal. You can apply governance to your API work in lots of different ways. For example, you could introduce a policy that all API teams in your company must use the same standardized technology stack. Or you could introduce a policy that all APIs need to pass a set of standardized quality measures before they can be launched. One policy is more heavy-handed than the other, but both policies might achieve similar results. In practice, you’ll be managing lots of different types of decisions at the same time and Understanding API Governance | 17
- 42. your governance systemis going to be a mix of many different constraints, rewards, policies, and processes. Keep in mind that governance always has a cost. Constraints need to be communica‐ ted, enforced, and maintained. Rewards that shape decision-making behavior need to be kept valuable and attractive to your audience. Standards, policies, and processes need to be documented, taught, and kept up to date. On top of that, constant infor‐ mation gathering is needed to observe the impact of all of this on the system. You may even need to hire more people just to support your governance efforts. Beyond those general costs of maintaining the machinery of governance, there are also the hidden costs of applying governance to your system. These are the impact costs that come up when you actually start governing the system. For example, if you mandate the technology stack that all developers must use, what is the organizational cost in terms of technological innovation? Also, what will be the cost to employee happiness? Will it become more difficult to attract good talent? It turns out that these kinds of costs are difficult to predict. That’s because in reality you’re governing a complex system of people, processes, and technology. To govern an API system, you’ll first need to learn what it takes to manage a complex system in general. Governing Complex Systems The good news is that you don’t need to control every single decision in your organi‐ zation to get great results from governance. The bad news is that you’ll need to figure out which decisions you will need to control in order to get those good results. That’s not an easy problem to solve, and you won’t find a definitive answer in this book. That’s because it’s impossible to give you an answer that will fit your unique context and goal. If all you wanted to do was bake a sponge cake, we could give you a pretty definitive recipe for making one. We’d tell you how much flour and how many eggs you’d need and what temperature to set your oven at. We could even tell you exactly how to check if the cake is done. That’s because there is very little variability in modern bak‐ ing. The ingredients are reasonably consistent no matter where you purchase them from. Ovens are designed to cook at specific, standardized temperatures. Most importantly, the goal is the same—a specific kind of cake. But you aren’t making a cake, and this isn’t a recipe book. You’ll need to deal with an incredible amount of variability. For example, the people in your company will have varying levels of decision-making talent. The regulatory constraints you operate in wiill be unique to your industry and location. You’ll also be serving your own dynamically changing consumer market with its own consumer culture. On top of all that, your organizational goals and strategy will be entirely unique to you. 18 | Chapter 2: API Governance
- 43. All this variabilitymakes it tough to prescribe a single correct “recipe” for API gover‐ nance. To make things even harder, there’s also the small problem of knock-on effects. Every time you introduce a rule, or create a new standard, or apply any form of governance, you’ll have to deal with unintended consequences. That’s because all the various parts of your organization are intertwined and connected. For example, to improve the consistency and quality of your API code, you could introduce a stan‐ dard technology stack. That new stack might result in bigger code packages as pro‐ grammers start adding more libraries and frameworks. And that could result in a change to the deployment process because the bigger deployment packages can’t be supported with the existing system. With the right information, maybe you could predict and prevent that outcome. But it’s impossible to do that for every possible eventuality, especially within a reasonable amount of time. Instead, you’ll need to accept the fact that you are working with a complex adaptive system. As it turns out, this is a feature, not a bug. You’ll just need to figure out how to use it to your advantage. Complex adaptive systems When we say that your organization is a complex adaptive system, we mean: • It has lots of parts that are interdependent (e.g., people, technologies, process, culture). • Those parts can change their behavior and adapt to system changes (e.g., chang‐ ing deployment practices when containerization is introduced). The universe is full of these kinds of systems, and the study of complexity has become an established scientific discipline. Even you yourself are a complex adaptive system. You might think of yourself as a single unit—a self—but “self” is just an abstraction. In reality, you’re a collection of organic cells, albeit a collection of cells that is capable of amazing feats: thinking, moving, sensing and reacting to external events as an emergent whole “being.” At the cellular level, your individual cells are specialized; old, dying cells are replaced and groups of cells work together to produce big impacts in your body. The complexity of the biological system that you are composed of makes your body highly resilient and adaptable. You’re probably not immortal, but you’re equally likely to be able to withstand massive amounts of environmental change and even bodily damage, thanks to your complex biological system. Usually, when we talk about “systems” in technology we focus on software systems and network-based architecture. Those kinds of systems can definitely grow to be complex. For example, the web is a perfect example of system-level complexity and emergence. A network of individual servers run independently, but through their dependencies and interconnections produce an emergent whole that we call “the web.” But most of that software isn’t really adaptive. Understanding API Governance | 19
- 44. The API softwareyou write today is pretty dumb. That doesn’t mean that your code is of poor quality or that it doesn’t do the job it was designed for. In fact, it’s just the opposite; most of the APIs you implement will do exactly what they’re supposed to do. And that’s the problem. You can make an API that’s smart enough to adapt to a changing traffic pattern or an increasing number of errors, but it’s impractical to make one that can add a new feature without human intervention, or correct a com‐ plex bug by itself, or update its own documentation to make it easier to learn. Now, all of that might change in the future. But as it stands today, it’s your people that drive the behavior of your software system. The good news is that people are very good at adapting (especially when compared to software). Your API organiza‐ tion is a complex adaptive system. All of the individual people in your organization make many local decisions, sometimes collectively and sometimes individually. When all those decisions happen at scale and over time, a system emerges. Just like your body, that system is capable of adapting to a lot of change. But working with a complex system requires a special kind of approach. It’s difficult to predict the impact of changes in a complex system—making a change to one part of your system can lead to unintended consequences in another part. That’s because the people in your organization are constantly adapting to the changing environ‐ ment. For example, introducing a rule that deploying software in “containers” is for‐ bidden would have a wide-reaching impact, affecting software design, hiring, deployment processes, and culture. All of this means that you can’t get the outputs you want from the system by imple‐ menting large changes and waiting for results. Instead, you’ll need to “nudge” the sys‐ tem by making smaller changes and assessing their impact. It requires an approach of continuous adjustment and improvement, in the same way you might tend to a gar‐ den, pruning branches, planting seeds, and watering while continuously observing and adjusting your approach. In Chapter 5, we’ll explore the concept of continuous improvement in more detail. Governing Decisions In the last section we introduced the concept of governing decisions inside a complex system. Hopefully, that’s helped you to understand a fundamental rule for API gover‐ nance: if you want your governance system to be effective, you’ll need to get better at managing decisions. We think one of the best ways to do that is to focus on where decisions are happening and who is making them. It turns out that there isn’t a single best way to map those decisions out. For example, consider how API design gover‐ nance could be handled in two different fictional companies: 20 | Chapter 2: API Governance
- 45. Company A: PendantSoftware At Pendant Software, all API teams are provided with access to the “Pendant Guidelines for API Design” e-book. These guidelines are published quarterly by Pendant’s API Center of Excellence and Enablement—a small team of API experts working inside the company. The guidelines contain highly prescriptive and very specific rules for designing APIs. All teams are expected to adhere to the guidelines and APIs are automatically tested for conformance before they can be published. As a result of these policies, Pendant has been able to publish a set of industry- leading, highly consistent APIs that developers rate very favorably. These APIs have helped Pendant differentiate itself from competitors in the marketplace. Company B: Vandelay Insurance At Vandelay, API teams are given the company’s business goals and expected results for their API products. These goals and results are defined by the execu‐ tive teams and are updated regularly. Each API team has the freedom to address an overall business goal in the manner they choose and multiple teams can pur‐ sue the same goal. API teams can design and implement APIs however they like, but every product must adhere to Vandelay’s enterprise measurement and moni‐ toring standards. The standards are defined by Vandelay’s System Commune, a group made up of individuals from each of the API teams who join voluntarily and define the set of standards that everyone needs to follow. As a result of these policies, Vandelay has been able to build a highly innovative, adaptive API architecture. This API system has enabled Vandelay to out- maneuver its competition with innovative business practices that can be deliv‐ ered very quickly in its technology platform. In our fictional case studies, both Pendant and Vandelay were wildly successful in their management of decision making. But the way they governed their work was incredibly different. Pendant found success with a highly centralized, authoritative approach, while Vandelay preferred a results-oriented method. Neither approach is “correct,” and both styles of governance have merit. To govern decisions effectively, you’ll need to address three key questions: 1. Which decisions should be managed? 2. Where should those decisions be made (and by whom)? 3. How will the system be impacted by your decision management strategy? Later in the book we’ll dig into the questions of which decisions should be managed and how those decisions will impact your system. For now, we’ll focus on the second question of where in the system the most important decisions should be made. To help you address decision distribution, we are going to dig deeper into the subject of Governing Decisions | 21
- 46. governing a decision.We’ll tackle the trade-off between centralized and de- centralized decision making and we’ll take a closer look at what it means to distribute a decision. Centralization and Decentralization Earlier in this chapter, we introduced the concept of a complex adaptive system and we used the human body as an example. These kinds of systems abound in nature, and you are surrounded by them. For example, the ecosystem of a small pond can be thought of as a complex adaptive system. It continues to survive thanks to the activi‐ ties and interdependence of the animals and vegetation that live in it. The ecosystem adapts to changing conditions thanks to the localized decision making of each of these living things. But the pond doesn’t have a manager, and there is no evidence that the frogs, snakes, and fish hold quarterly management meetings. Instead, each agent in the system makes individual decisions and exhibits individual behaviors. Taken together these individual decisions and actions form a collective, emergent whole that can survive even as individual parts of the system change or appear and disappear over time. Like most of the natural world, the pond system succeeds because system-level decisions are decentralized and distributed. As we established earlier, your organization is also a complex adaptive system. It’s a product of all the collective individual decisions made by your employees. Just like in a human body or a pond ecosystem, if you were to allow individual workers to have complete freedom and autonomy, the organization as a whole would become more resilient and adaptive. You’d have a bossless, decentralized organization that could find its way thanks to the individual decisions of its employees (see Figure 2-1). Figure 2-1. A decentralized organization 22 | Chapter 2: API Governance
- 47. You could dothis, but you might run into some problems, primarily because it’s dif‐ ficult to succeed with a free-market organization in exactly the same way that com‐ plex systems succeed in nature. The biosystem of a pond is directed by the hand of natural selection. Every agent in the system has become optimized for the survival of its species. There’s no system-level goal beyond survival. On top of that, in nature it’s normal for systems to fail. For example, if an invasive species is introduced the entire pond system might die. In the natural world, that can be OK because something else might take its place—the system as a whole remains resilient. However, businesses leaders don’t respond well to this level of uncertainty and lack of control. Chances are you’ll need to steer your system toward specific goals that go beyond survival. Also, it’s likely that you aren’t willing to risk letting your company die for the sake of a better company taking its place. You’ll almost certainly want to reduce the risk that any individual agent can destroy the whole company because of a bad decision. That means you’ll need to reduce decision-making freedom for individ‐ uals and introduce some accountability. One way of doing that is to introduce deci‐ sion centralization (Figure 2-2). Figure 2-2. A centralized organization By this, we mean that decision making is constrained to a particular person or team in your organization. That centralized team makes a decision that the rest of the com‐ pany will need to adhere to. Decentralization is the opposite case: individual teams can make decisions that only they need to adhere to. The truth is that there is no perfectly centralized or perfectly decentralized organiza‐ tion. Instead, different types of decisions are distributed within the organization in different ways—some are more centralized while others are more decentralized. You’ll need to decide how to distribute the decisions that impact your system the Governing Decisions | 23
- 48. most. So, whichones should be more centralized and which ones should be more decentralized? Remember, a primary goal of governing decisions is to help your organization suc‐ ceed and survive. What that means is entirely dependent on your business context, but generally speaking it means that decisions need to be timely enough to enable business agility and of sufficient quality to improve the business (or at the very least avoid damaging it). There are three factors that impact the ability to make decisions: Availability and accuracy of information It’s really difficult to make a good decision if you base it on information that is incorrect or missing. That could mean being misled about the goal or context of the decision, but it could also mean not knowing what the decision’s impact will be on the system. Most of the time, we assume the responsibility for gathering decision-making information rests at the feet of the decision makers. But for the purposes of distributing decisions, we also need to think about how centralizing or decentralizing a decision affects the information that’s available. Decision-making talent Generally speaking, decision quality improves if the decision maker is good at making high-quality decisions. Or, in simpler language—highly talented people with lots of experience will make better decisions than less-talented people with no experience. When it comes to distributing decision making, the challenge is to also distribute your talent in a way that helps you the most. Coordination costs Complex decisions can’t be made in a timely manner unless the decision making is shared. But whenever you share decision-making work you’ll incur a coordina‐ tion cost. If that coordination cost grows too high, you won’t be able to make decisions quickly enough. Centralization and decentralization of decisions can have a big impact on coordination costs. Thinking about decisions in terms of these factors will help you decide when a deci‐ sion should be centralized or decentralized. To help you understand how to do that, we’ll take a look at it from two perspectives: scope of optimization and scale of opera‐ tion. Let’s start by digging into scope and its relationship with decision-making infor‐ mation. Scope of optimization The big difference between a centralized decision and a decentralized decision has to do with their scope. When you make a centralized decision, you are making it for the entire organization. So, your scope for the decision includes the whole system and your goal is to make a decision that improves that system. Another way of saying this is that the decision you are making is meant to optimize the system scope. For 24 | Chapter 2: API Governance
- 49. example, a centralizedteam might decide on a development methodology for the entire company to follow. The same team might also make decisions about which APIs in the system should be retired. Both of these decisions would be made with the goal of doing what’s best for the entire system. Conversely, the primary characteristic of a decentralized decision is that it is opti‐ mized for a local scope. When you are optimizing for the local scope, you are making a decision that will improve your local context—the set of information that pertains only to your local situation. While your decision might have an impact on the wider system, your goal is to improve your local results. For example, an API team can make a local decision to use a waterfall development process because they’re sharing the work with an external company that insists on it. The great thing about decentralized decision making is that it can help you make big gains in efficiency, innovation, and agility for your business overall. That’s because decentralized decision makers are able to limit their scope of information to a local context that they understand. This means they can form a decision based on accurate information about their own problem space, which helps them produce better deci‐ sions. For any modern business that is trying to succeed with a strategy of agility and innovation, the decentralized decision pattern should be the default approach. However, making decisions that focus only on optimizing the local scope can cause problems, particularly if those decisions have the potential to impact the system neg‐ atively and in irreversible ways. When Amazon CEO Jeff Bezos talks about the impact of decisions, he splits them into two types: “type 1” decisions that can be easily reversed if they are wrong and “type 2” decisions that are near impossible to recover from. For example, a lot of big companies choose to centralize decisions about API security configuration to prevent a local optimization from creating a sys‐ tem vulnerability. Beyond dangers to the system, there are times when system-level consistency is more valuable than local optimization. For example, an individual API team might choose an API style that makes the most sense for their problem domain. But if every API team chooses a different API style, the job of learning to use each API becomes more difficult due to a lack of consistency, especially when many APIs need to be used to accomplish a single task. In this case, optimizing the API style decision for the system scope might be better. You’ll need to think about the scope of optimization carefully when you plan where a decision should happen. If a decision has the potential to impact your system in an irreversible way, start by centralizing it so that it can be optimized for system scope. If decision quality could benefit from the local context of information, start by decen‐ tralizing it. If decentralizing a decision could result in unacceptable inconsistency at the system level, consider centralizing it. Governing Decisions | 25
- 50. Scale of operation Ifyou had unlimited resources for making good decisions, you’d only need to think about scope for decision making. But you don’t. So, in addition to scope, you’ll need to think about the scale of decisions being made. That’s because if there is a bigger decision demand, there will be more pressure on your decision-making talent supply and an upward pressure on your coordination costs. If you want your API work to scale as your organization grows, you’ll need to plan your decision distribution pat‐ tern carefully. Decentralizing a decision creates a big talent demand when you are operating at scale. When you decentralize a decision you are distributing it to more than one team. If you want all of those decisions to be high quality, you’ll need to fill each of those teams with talented decision makers. If you can’t afford to do that, you’ll end up gen‐ erating lots of bad decisions. So, it’s worthwhile to hire the best decision-makers you can for every decision making position in your company. Unfortunately, hiring good people isn’t an industry secret. There are a limited num‐ ber of talented and experienced people available and a lot of companies competing to hire them. Some companies are willing to spend whatever it takes to make sure that they get the best talent in the world. If you are lucky enough to be in that situation, you can decentralize more of your decisions because you have the talent to make them. Otherwise, you’ll need to be more pragmatic with your distribution decisions. If your supply of top-level, “grade A” decision-making talent is limited, you may choose to pool that talent together and centralize the most important decisions to that group of people. That way, you have a greater chance of producing better deci‐ sions, faster. But an increasing scale of decision demand wreaks havoc on this model too, because as the demand for decision making grows, the centralized team will need to grow along with it. As the team grows, so too will the cost of coordinated decision making. No matter how talented the people are, the cost of coordinating a decision grows as you add more people. Eventually you’ll reach a number that makes it impos‐ sible to reach decisions affordably. All of this means that decision distribution will involve a lot of trade-offs. If the deci‐ sion is highly impactful, like the “type 1” decisions that Jeff Bezos describes, you’ll need to centralize it and pay the price of lower decision-making throughput. Con‐ versely, if speed and local optimization are most important, you can decentralize the decision and either pay for better people or accept the net reduction in quality of decisions. That said, there is a way to manage this trade-off in a more nuanced and flexible way. It involves distributing the parts of the decision instead of the entre decision itself, and it’s what we are going to focus on in the next section. 26 | Chapter 2: API Governance
- 51. The Elements ofa Decision It’s difficult to distribute a decision in the way we’ve described so far because it’s a bit of an all-or-nothing affair. Do you let your teams decide which development method they want to use, or do you choose one and make every team use it? Do you let the teams decide when their API should retire, or do you take the choice away from them completely? In reality, governance requires more nuance. In this section, we’ll explore a way of distributing decisions with more flexibility by breaking them up into pieces. Instead of distributing the entire decision, you can distribute parts of the decision. That way you can get the benefits of system-level optimization along with highly con‐ textual local optimization at the same time. Some parts of a decision can be central‐ ized while other parts are decentralized. To help you accomplish distribution with this kind of precision, we’ve broken down API decisions into the six decision elements you’ll need to distribute (see Figure 2-3): Figure 2-3. Decision elements This isn’t meant to be an authoritative, universal model for decision making. Instead, it’s a model that we’ve developed to distinguish the parts of a decision that have the biggest impact on a system when they are either centralized or decentralized. These parts are based on the various five-, six-, and seven-step models of decision-making that abound in the business management domain. Although the steps we’ll describe could be applied to a decision made by a single person, they’re most useful when we are talking about decisions made in coordination between a group of people. Let’s start by taking a look at how distributing the inception of a decision impacts your system. Inception Every decision happens because someone thinks that decision needed to be made. It means that someone has identified that a problem or opportunity exists with more than one possible solution. Sometimes this is obvious, but in many cases spotting a decision-making opportunity requires talent and expertise. You’ll need to think Governing Decisions | 27
- 52. about which decisionswill naturally ignite on their own and which ones will need special handling to make sure that they happen. Kicking off decisions about API work happens naturally in the course of day-to-day problem solving. For example, choosing which database to use for storing persistent data would be a difficult decision for a typical implementer to ignore. The decision happens because the work can’t continue without it. But there will also be situations where you’ll need to force inception to happen. This is usually for one of two reasons: Habitualized decision making Over time, if a team makes the same decision over and over, the decision may disappear. That is, the possibilities are no longer considered and instead an assumption is made that work will continue in the same way it always has. For example, if every API implementation is written in the Java programming lan‐ guage, it may not occur to anyone to consider a different choice of language. Decision blindness Sometimes, teams will miss opportunities to make impactful decisions. This can happen because of habit, but also because of limited information, experience, or talent. For example, a team may focus on the choice of which database to use for storage, but fail to identify that the API could be designed in a way that doesn’t require persistent storage. Not every decision needs to happen, and it’s perfectly fine for decisions to be missed or for a cultural habit to make them implicit. It’s only a problem if not making a deci‐ sion negatively impacts the results you are getting from your APIs. Arbitrarily demanding that more decisions happen could have a nightmarish impact on produc‐ tivity. Instead, the role of API governance is to generate more of the decisions that will lead to optimal results and less of the decisions that will provide little value. Choice generation It’s hard to choose if you don’t know your options, and that’s what this element is all about. Choice generation is the work of identifying the choices to choose from. If you’re making a decision in a domain you have a lot of experience in, generating choices can be pretty easy. But if there are lots of unknowns, you’ll need to spend more time identifying the possibilities. For example, an experienced C programmer already has a good idea of their options when they are deciding on a loop structure, but a beginner will probably need to do some investigation to learn that they can use a for loop or a while loop and the differences between the two. Even if you know a domain fairly well, you’ll probably spend more time on choice generation if the cost and impact of the decision are very high. For example, you may have intimate knowledge of the different cloud hosting environments, but will still perform your due diligence of research when it comes time to sign a contract with 28 | Chapter 2: API Governance
- 53. one of them.Are there new vendors available that you didn’t know about? Are the prices and terms still the same as you remember? From a governance perspective, choice generation is important because it’s where the boundaries of decision making are set. This is especially useful when the people com‐ ing up with the list of choices are not the same as the people making the selection. For example, you could standardize a list of possible API description formats, but let individual teams decide which format they like best. If you take this approach you’ll need to be careful about the quality of the “menu” you are providing. If the choices are overly restrictive or of poor quality, you’ll run into problems. Selection Selection is the act of choosing from the list of possible options. Selection is the heart of decision making and it’s the step most people focus on, but the importance of the selection element depends a lot on the scope of choices that have been made avail‐ able. If that scope is very wide, then the selection process is integral to the quality of the decision. But if that scope has been constrained to safe choices with little differen‐ tiating them, the selection step can be quick and less impactful. Let’s walk through an example of this in action. Suppose you’re responsible for con‐ figuring Transport Layer Security (TLS) for your HTTP API. Part of that work includes a decision on which cipher suites (sets of cryptography algorithms) the server should support. It’s an important decision because some cipher suites have become vulnerable with age, so picking the wrong ones can make your API less secure. Also, if you choose cipher suites that your users’ client software doesn’t understand, nobody will be able to use your API. In one scenario, you might be given a list of all the known cipher suites and asked to select the ones that the server should support. In this case, selection would need spe‐ cial care. You’d probably do a lot of research and only feel comfortable making a selection once you’d gathered as much information as possible. In fact, if you didn’t have a good amount of experience securing servers, you’d probably look for someone who did and ask them to make a selection for you. But what if instead of being given the set of all possible cipher suites, you were given a curated list of them? The list of options might also include relevant information about how well supported each cipher suite is and what the known vulnerabilities are. Armed with this information you could probably make a faster choice. Equally, you’re choice is likely to be safer because your decision scope is limited to choices that have been deemed safe enough to use. In this case, you’d make a decision based on what you know about the clients using the API and the sensitivity and business importance of the API. Finally, you might be given only one choice: a single cipher suite that you must use. A single-choice decision makes selection a trivial affair—the decision has been made for Governing Decisions | 29
- 54. you. In thiscase, the quality of the decision is entirely dependent on the people who generated that choice. Hopefully it’s a good fit for the specific requirements you have. So, the importance of selection depends a lot on the scope of the choices offered. There’s a bit of a trade-off at work here. If you push more of the decision-making investment into choice generation you’ll spend less time on selection, and vice-versa. That has implications for how you distribute decision elements and who should be responsible for them. Whichever decision element becomes more important will require a suitably talented decision maker to make it. It also means you can combine system scope and local scope by distributing choice generation and choice selection. For example, you can centralize the generation of development method choices based on the system context while still allowing indi‐ vidual teams to choose their preferred method using their local context. This happens to be a particularly useful pattern for governing large API landscapes at scale and pre‐ serving both safety and speed of change. Authorization Just because a choice has been selected doesn’t mean the decision is done. The selec‐ tion needs to be authorized before it can be realized. Authorization is the work of deciding on the validity of the selected choice. Was the right selection made? Is it implementable? Is it safe? Does it make sense in the context of other decisions that have been made? Authorization can be implicit or explicit. When authorization is explicit it means that someone or some team must expressly authorize the decision before it can go for‐ ward. It becomes an approval step in the decision-making process. We’re sure you’ve been involved in many decisions that required some kind of approval. For example, in many companies, workers can select their holiday time from a list of work dates, but it’s up to their manager to make the final approval decision on the schedule. Implicit authorization means that authorization happens automatically when some set of criteria has been met. Examples of this are the role of the person making the selection, the cost of the selection that was made, or adherence to a specific policy. In particular, authorization can become implicit when the person making the selection is also the person authorizing the selection. In effect, they become their own approver. Explicit authorization is useful because it can further improve the safety of the deci‐ sion. But if there are lots of decisions being made and all of them are being centrally authorized, then there is likely to be a reduction in decision speed. Lots of people will end up waiting for their approvals. Implicit authorization greatly increases the speed of decision making by empowering selection, but comes with greater risk. 30 | Chapter 2: API Governance
- 55. Other documents randomlyhave different content
- 56. also acted asa talebearer, suppressed the murmurings that were going about among the soldiers, he treated secretly and underhandedly with several gentlemen who agreed with him. They set the soldiers to talking about going back to New Spain, in little knots and gatherings, and induced them to hold consultations about it, and had them send papers to the general, signed by all the soldiers, through their ensigns, asking for this. They all entered into it readily, and not much time needed to be spent, since many desired it already. When they asked him, the general acted as if he did not want to do it, but all the gentlemen and captains supported them, giving him their signed opinions, and as some were in this, they could give it at once, and they even persuaded others to do the same. Thus they made it seem as if they ought to return to New Spain, because they had not found any riches, nor had they discovered any settled country out of which estates could be formed for all the army. When he had obtained their signatures, the return to New Spain was at once announced, and since nothing can ever be concealed, the double dealing began to be understood, and many of the gentlemen found that they had been deceived and had made a mistake. They tried in every way to get their signatures back again from the general, who guarded them so carefully that he did not go out of one room, making his sickness seem very much worse, and putting guards about his person and room, and at night about the floor on which he slept. In spite of all this, they stole his chest, and it is said that they did not find their signatures in it, because he kept them in his mattress; on the other hand, it is said that they did recover them. They asked the general to give them sixty picked men, with whom they would remain and hold the country until the viceroy could send them support, or recall them, or else that the general would leave them the army and pick out sixty men to go back with him. But the soldiers did not want to remain either way, some because they had turned their prow toward New Spain, and others because they saw clearly the trouble that would arise over who should have the command. The gentlemen, I do not know whether because they had sworn fidelity or because they feared that the soldiers would not support them, did what had been decided on,
- 57. although with anill-will, and from this time on they did not obey the general as readily as formerly, and they did not show any affection for him. He made much of the soldiers and humored them, with the result that he did what he desired and secured the return of the whole army.
- 58. Chapter 3 Of therebellion at Suya and the reasons the settlers gave for it. We have already stated in the last chapter that Don Garcia Lopez de Cardenas came back from Suya in flight, having found that country risen in rebellion. He told how and why that town was deserted, which occurred as I will relate. The entirely worthless fellows were all who had been left in that town, the mutinous and seditious men, besides a few who were honored with the charge of public affairs and who were left to govern the others. Thus the bad dispositions of the worthless secured the power, and they held daily meetings and councils and declared that they had been betrayed and were not going to be rescued, since the others had been directed to go through another part of the country, where there was a more convenient route to New Spain, which was not so, because they were still almost on the direct road. This talk led some of them to revolt, and they chose one Pedro de Avila as their captain. They went back to Culiacan, leaving the captain, Diego de Alcaraz, sick in the town of San Hieronimo, with only a small force. He did not have anyone whom he could send after them to compel them to return. They killed a number of people at several villages along the way. Finally they reached Culiacan, where Hernando Arias de Saabedra, [540] who was waiting for Juan Gallego to come back from New Spain with a force, detained them by means of promises, so that Gallego could take them back. Some who feared what might happen to them ran away one night to New Spain. Diego de Alcaraz, who had remained at Suya with a small force, sick, was not able to hold his position, although he would have liked to, on account of the poisonous herb which the natives use.[541] When these noticed how weak the Spaniards were, they did not continue to trade with them as they formerly had done. Veins of gold had already been
- 59. discovered before this,but they were unable to work these, because the country was at war. The disturbance was so great that they did not cease to keep watch and to be more than usually careful. The town was situated on a little river.[542] One night they suddenly saw fires which they were not accustomed to, and on this account they doubled the watches, but not having noticed anything during the whole night, they grew careless along toward morning, and the enemy entered the village so silently that they were not seen until they began to kill and plunder. A number of men reached the plain as well as they could, but while they were getting out the captain was mortally wounded. Several Spaniards came back on some horses after they had recovered themselves and attacked the enemy, rescuing some, though only a few. The enemy went off with the booty, leaving three Spaniards killed[543] besides many of the servants and more than twenty horses. The Spaniards who survived started off the same day on foot, not having any horses. They went toward Culiacan, keeping away from the roads, and did not find any food until they reached Corazones where the Indians, like the good friends they have always been, provided them with food. From here they continued to Culiacan, undergoing great hardships. Hernandarias de Saabedra, the mayor, received them and entertained them as well as he could until Juan Gallego arrived with the reinforcements which he was conducting, on his way to find the army. He was not a little troubled at finding that post deserted, when he expected that the army would be in the rich country which had been described by the Indian called Turk, because he looked like one.
- 60. Chapter 4 Of howFriar Juan de Padilla and Friar Luis remained in the country and the army prepared to return to Mexico. When the general, Francisco Vasquez, saw that everything was now quiet, and that his schemes had gone as he wished, he ordered that everything should be ready to start on the return to New Spain by the beginning of the month of April, in the year 1543 [1542]. Seeing this, Friar Juan de Padilla, a regular brother of the lesser order, and another, Friar Luis,[544] a lay brother, told the general that they wanted to remain in that country—Friar Juan de Padilla in Quivira, because his teachings seemed to promise fruit there, and Friar Luis at Cicuye. On this account, as it was Lent at the time, the father made this the subject of his sermon to the companies one Sunday, establishing his proposition on the authority of the Holy Scriptures. He declared his zeal for the conversion of these peoples and his desire to draw them to the faith, and stated that he had received permission to do it, although this was not necessary. The general sent a company to escort them as far as Cicuye, where Friar Luis stopped, while Friar Juan went on back to Quivira with the guides who had conducted the general, taking with him the Portuguese, as we related, and the half-blood, and the Indians from New Spain. He was martyred a short time after he arrived there, as we related in the second part, Chapter 8. Thus we may be sure that he died a martyr, because his zeal was holy and earnest. Friar Luis remained at Cicuye. Nothing more has been heard about him since, but before the army left Tiguex some men who went to take him a number of sheep that were left for him to keep, met him as he was on his way to visit some other villages, which were fifteen or twenty leagues from Cicuye, accompanied by some followers. He
- 61. felt very hopefulthat he was liked at the village and that his teaching would bear fruit, although he complained that the old men were falling away from him. I, for my part, believe that they finally killed him. He was a man of good and holy life, and may Our Lord protect him and grant that he may convert many of those peoples, and end his days in guiding them in the faith. We do not need to believe otherwise, for the people in those parts are pious and not at all cruel. They are friends, or rather, enemies of cruelty, and they remained faithful and loyal friends.[545] After the friars had gone, the general, fearing that they might be injured if people were carried away from that country to New Spain, ordered the soldiers to let any of the natives who were held as servants go free to their villages whenever they might wish. In my opinion, though I am not sure, it would have been better if they had been kept and taught among Christians. The general was very happy and contented when the time arrived and everything needed for the journey was ready, and the army started from Tiguex on its way back to Cibola. One thing of no small note happened during this part of the trip. The horses were in good condition for their work when they started, fat and sleek, but more than thirty died during the ten days which it took to reach Cibola, and there was not a day in which two or three or more did not die. A large number of them also died afterward before reaching Culiacan, a thing that did not happen during all the rest of the journey. After the army reached Cibola, it rested before starting across the wilderness, because this was the last of the settlements in that country. The whole country was left well disposed and at peace, and several of our Indian allies remained there.[546]
- 62. Chapter 5 Of howthe army left the settlements and marched to Culiacan, and of what happened on the way. Leaving astern, as we might say, the settlements that had been discovered in the new land, of which, as I have said, the seven villages of Cibola were the first to be seen and the last that were left, the army started off, marching across the wilderness. The natives kept following the rear of the army for two or three days, to pick up any baggage or servants, for although they were still at peace and had always been loyal friends, when they saw that we were going to leave the country entirely, they were glad to get some of our people in their power, although I do not think that they wanted to injure them, from what I was told by some who were not willing to go back with them when they teased and asked them to. Altogether, they carried off several people besides those who had remained of their own accord, among whom good interpreters could be found to-day. The wilderness was crossed without opposition, and on the second day before reaching Chichilticalli Juan Gallego met the army, as he was coming from New Spain with reenforcements of men and necessary supplies for the army, expecting that he would find the army in the country of the Indian called Turk. When Juan Gallego saw that the army was returning, the first thing he said was not, "I am glad you are coming back," and he did not like it any better after he had talked with the general. After he had reached the army, or rather the quarters, there was quite a little movement among the gentlemen toward going back with the new force which had made no slight exertions in coming thus far, having encounters every day with the Indians of these regions who had risen in revolt, as will be related. There was talk of making a settlement somewhere in that region until the viceroy could receive an account of what had
- 63. occurred. Those soldierswho had come from the new lands would not agree to anything except the return to New Spain, so that nothing came of the proposals made at the consultations, and although there was some opposition, they were finally quieted. Several of the mutineers who had deserted the town of Corazones came with Juan Gallego, who had given them his word as surety for their safety, and even if the general had wanted to punish them, his power was slight, for he had been disobeyed already and was not much respected. He began to be afraid again after this, and made himself sick, and kept a guard. In several places yells were heard and Indians seen, and some of the horses were wounded and killed, before Batuco[547] was reached, where the friendly Indians from Corazones came to meet the army and see the general. They were always friendly and had treated all the Spaniards who passed through their country well, furnishing them with what food they needed, and men, if they needed these. Our men had always treated them well and repaid them for these things. During this journey the juice of the quince was proved to be a good protection against the poison of the natives, because at one place, several days before reaching Señora, the hostile Indians wounded a Spaniard called Mesa, and he did not die, although the wound of the fresh poison is fatal, and there was a delay of over two hours before curing him with the juice. The poison, however, had left its mark upon him. The skin rotted and fell off until it left the bones and sinews bare, with a horrible smell. The wound was in the wrist, and the poison had reached as far as the shoulder when he was cured. The skin on all this fell off. The army proceeded without taking any rest, because the provisions had begun to fail by this time. These districts were in rebellion, and so there were not any victuals where the soldiers could get them until they reached Petlatlan, although they made several forays into the cross country in search of provisions. Petlatlan is in the province of Culiacan, and on this account was at peace, although they had several surprises after this.[548] The army rested here several days to get provisions. After leaving here they were able to travel more
- 64. quickly than before,for the thirty leagues of the valley of Culiacan, where they were welcomed back again as people who came with their governor, who had suffered ill treatment.
- 65. Chapter 6 Of howthe general started from Culiacan to give the viceroy an account of the army with which he had been intrusted. It seemed, indeed, as if the arrival in the valley of Culiacan had ended the labors of this journey, partly because the general was governor there and partly because it was inhabited by Christians. On this account some began to disregard their superiors and the authority which their captains had over them, and some captains even forgot the obedience due to their general. Each one played his own game, so that while the general was marching toward the town, which was still ten leagues away, many of the men, or most of them, left him in order to rest in the valley, and some even proposed not to follow him. The general understood that he was not strong enough to compel them, although his position as governor gave him fresh authority. He determined to accomplish it by a better method, which was to order all the captains to provide food and meat from the stores of several villages that were under his control as governor. He pretended to be sick, keeping his bed, so that those who had any business with him could speak to him or he with them more freely, without hindrance or observation, and he kept sending for his particular friends in order to ask them to be sure to speak to the soldiers and encourage them to accompany him back to New Spain, and to tell them that he would request the viceroy, Don Antonio de Mendoza, to show them especial favor, and that he would do so himself for those who might wish to remain in his government. After this had been done, he started with his army at a very bad time, when the rains were beginning, for it was about Saint John's day,[549] at which season it rains continuously. In the uninhabited country which they passed through as far as Compostela there are numerous very dangerous rivers, full of large and fierce alligators. While the
- 66. army was haltingat one of these rivers, a soldier who was crossing from one side to the other was seized, in sight of everybody, and carried off by an alligator without its being possible to help him. The general proceeded, leaving the men who did not want to follow him all along the way, and reached Mexico with less than 100 men. He made his report to the viceroy, Don Antonio de Mendoza, who did not receive him very graciously, although he gave him his discharge. His reputation was gone from this time on. He kept the government of New Galicia, which had been entrusted to him, for only a short time, when the viceroy took it himself, until the arrival of the court, or audiencia, which still governs it. And this was the end of those discoveries and of the expedition which was made to these new lands. It now remains for us to describe the way in which to enter the country by a more direct route, although there is never a short cut without hard work. It is always best to find out what those know who have prepared the way, who know what will be needed. This can be found elsewhere, and I will now tell where Quivira lies, what direction the army took, and the direction in which Greater India lies, which was what they pretended to be in search of, when the army started thither. Today, since Villalobos[550] has discovered that this part of the coast of the South Sea trends toward the west, it is clearly seen and acknowledged that, since we were in the north, we ought to have turned to the west instead of toward the east, as we did. With this, we will leave this subject and will proceed to finish this treatise, since there are several noteworthy things of which I must give an account, which I have left to be treated more extensively in the two following chapters.
- 67. Chapter 7 Of theadventures of Captain Juan Gallego while he was bringing reenforcements through the revolted country. One might well have complained when in the last chapter I passed in silence over the exploits of Captain Juan Gallego with his twenty companions. I will relate them in the present chapter, so that in times to come those who read about it or tell of it may have a reliable authority on whom to rely. I am not writing fables, like some of the things which we read about nowadays in the books of chivalry. If it were not that those stories contained enchantments, there are some things which our Spaniards have done in our own day in these parts, in their conquests and encounters with the Indians, which, for deeds worthy of admiration, surpass not only the books already mentioned, but also those which have been written about the twelve peers of France, because, if the deadly strength which the authors of those times attributed to their heroes and the brilliant and resplendent arms with which they adorned them, are fully considered, and compared with the small stature of the men of our time and the few and poor weapons which they have in these parts, the remarkable things which our people have undertaken and accomplished with such weapons are more to be wondered at to-day than those of which the ancients write, and just because, too, they fought with barbarous naked people, as ours have with Indians, among whom there are always men who are brave and valiant and very sure bowmen, for we have seen them pierce the wings while flying, and hit hares while running after them. I have said all this in order to show that some things which we consider fables may be true, because we see greater things every day in our own times, just as in future times people will greatly wonder at the deeds of Don Fernando Cortes, who dared to go into the midst of New Spain with
- 68. 300 men againstthe vast number of people in Mexico, and who with 500 Spaniards succeeded in subduing it, and made himself lord over it in two years. The deeds of Don Pedro de Alvarado in the conquest of Guatemala, and those of Montejo in Tabasco, the conquests of the mainland and of Peru, were all such as to make me remain silent concerning what I now wish to relate; but since I have promised to give an account of what happened on this journey, I want the things I am now going to relate to be known as well as those others of which I have spoken. The captain Juan Gallego, then, reached the town of Culiacan with a very small force. There he collected as many as he could of those who had escaped from the town of Hearts, or, more correctly, from Suya, which made in all twenty-two men, and with these he marched through all of the settled country, across which he travelled 200 leagues with the country in a state of war and the people in rebellion, although they had formerly been friendly toward the Spaniards, having encounters with the enemy almost every day. He always marched with the advance guard, leaving two-thirds of his force behind with the baggage. With six or seven Spaniards, and without any of the Indian allies whom he had with him, he forced his way into their villages, killing and destroying and setting them on fire, coming upon the enemy so suddenly and with such quickness and boldness that they did not have a chance to collect or even to do anything at all, until they became so afraid of him that there was not a town which dared wait for him, but they fled before him as from a powerful army; so much so, that for ten days, while he was passing through the settlements, they did not have an hour's rest. He did all this with his seven companions, so that when the rest of the force came up with the baggage there was nothing for them to do except to pillage, since the others had already killed and captured all the people they could lay their hands on and the rest had fled. They did not pause anywhere, so that although the villages ahead of him received some warning, they were upon them so quickly that they did not have a chance to collect. Especially in the region where the town of Hearts had been, he killed and hung a large number of
- 69. people to punishthem for their rebellion. He did not lose a companion during all this, nor was anyone wounded, except one soldier, who was wounded in the eyelid by an Indian who was almost dead, whom he was stripping. The weapon broke the skin and, as it was poisoned, he would have had to die if he had not been saved by the quince juice; he lost his eye as it was. These deeds of theirs were such that I know those people will remember them as long as they live, and especially four or five friendly Indians who went with them from Corazones, who thought that they were so wonderful that they held them to be something divine rather than human.[551] If he had not fallen in with our army as he did, they would have reached the country of the Indian called Turk, which they expected to march to, and they would have arrived there without danger on account of their good order and the skill with which he was leading them, and their knowledge and ample practice in war. Several of these men are still in this town of Culiacan, where I am now writing this account and narrative, where they, as well as I and the others who have remained in this province, have never lacked for labor in keeping this country quiet, in capturing rebels, and increasing in poverty and need, and more than ever at the present hour, because the country is poorer and more in debt than ever before.
- 70. Chapter 8 Which describessome remarkable things that were seen on the plains, with a description of the bulls. My silence was not without mystery and dissimulation when, in Chapter 7 of the second part of this book, I spoke of the plains and of the things of which I will give a detailed account in this chapter, where all these things may be found together; for these things were remarkable and something not seen in other parts. I dare to write of them because I am writing at a time when many men are still living who saw them and who will vouch for my account. Who could believe that 1,000 horses and 500 of our cows and more than 5,000 rams and ewes and more than 1,500 friendly Indians and servants, in travelling over those plains, would leave no more trace where they had passed than if nothing had been there—nothing—so that it was necessary to make piles of bones and cow-dung now and then, so that the rear guard could follow the army. The grass never failed to become erect after it had been trodden down, and, although it was short, it was as fresh and straight as before. Another thing was a heap of cow bones, a crossbow shot long, or a very little less, almost twice a man's height in places, and some eighteen feet or more wide, which was found on the edge of a salt lake in the southern part, and this in a region where there are no people who could have made it. The only explanation of this which could be suggested was that the waves which the north winds must make in the lake had piled up the bones of the cattle which had died in the lake, when the old and weak ones who went into the water were unable to get out. The noticeable thing is the number of cattle that would be necessary to make such a pile of bones.
- 71. Now that Iwish to describe the appearance of the bulls, it is to be noticed first that there was not one of the horses that did not take flight when he saw them first, for they have a narrow, short face, the brow two palms across from eye to eye, the eyes sticking out at the side, so that, when they are running, they can see who is following them. They have very long beards, like goats, and when they are running they throw their heads back with the beard dragging on the ground. There is a sort of girdle round the middle of the body. The hair is very woolly, like a sheep's, very fine, and in front of the girdle the hair is very long and rough like a lion's. They have a great hump, larger than a camel's. The horns are short and thick, so that they are not seen much above the hair. In May they change the hair in the middle of the body for a down, which makes perfect lions of them. They rub against the small trees in the little ravines to shed their hair, and they continue this until only the down is left, as a snake changes his skin. They have a short tail, with a bunch of hair at the end. When they run, they carry it erect like a scorpion. It is worth noticing that the little calves are red and just like ours, but they change their color and appearance with time and age. Another strange thing was that all the bulls that were killed had their left ears slit, although these were whole when young. The reason for this was a puzzle that could not be guessed. The wool ought to make good cloth on account of its fineness, although the color is not good, because it is the color of buriel.[552] Another thing worth noticing is that the bulls travelled without cows in such large numbers that nobody could have counted them, and so far away from the cows that it was more than forty leagues from where we began to see the bulls to the place where we began to see the cows. The country they travelled over was so level and smooth that if one looked at them the sky could be seen between their legs, so that if some of them were at a distance they looked like smooth- trunked pines whose tops joined, and if there was only one bull it looked as if there were four pines. When one was near them, it was impossible to see the ground on the other side of them. The reason
- 72. for all thiswas that the country seemed as round as if a man should imagine himself in a three-pint measure, and could see the sky at the edge of it, about a crossbow shot from him, and even if a man only lay down on his back he lost sight of the ground. I have not written about other things which were seen nor made any mention of them, because they were not of so much importance, although it does not seem right for me to remain silent concerning the fact that they venerate the sign of the cross in the region where the settlements have high houses. For at a spring which was in the plain near Acuco they had a cross two palms high and as thick as a finger, made of wood with a square twig for its crosspiece, and many little sticks decorated with feathers around it, and numerous withered flowers, which were the offerings.[553] In a graveyard outside the village at Tutahaco there appeared to have been a recent burial. Near the head there was another cross made of two little sticks tied with cotton thread, and dry withered flowers.[554] It certainly seems to me that in some way they must have received some light from the cross of Our Redeemer, Christ, and it may have come by way of India, from whence they proceeded.
- 73. Chapter 9 Which treatsof the direction which the army took, and of how another more direct way might be found, if anyone was to return to that country. I very much wish that I possessed some knowledge of cosmography or geography, so as to render what I wish to say intelligible, and so that I could reckon up or measure the advantage those people who might go in search of that country would have if they went directly through the centre of the country, instead of following the road the army took. However, with the help of the favor of the Lord, I will state it as well as I can, making it as plain as possible. It is, I think, already understood that the Portuguese, Campo, was the soldier who escaped when Friar Juan de Padilla was killed at Quivira, and that he finally reached New Spain from Panuco,[555] having travelled across the plains country until he came to cross the North Sea mountain chain, keeping the country that Don Hernando de Soto discovered all the time on his left hand, since he did not see the river of the Holy Spirit (Espiritu Santo) at all.[556] After he had crossed the North Sea mountains, he found that he was in Panuco, so that if he had not tried to go to the North Sea, he would have come out in the neighborhood of the border land, or the country of the Sacatecas,[557] of which we now have some knowledge. This way would be somewhat better and more direct for anyone going back there in search of Quivira, since some of those who came with the Portuguese are still in New Spain to serve as guides. Nevertheless, I think it would be best to go through the country of the Guachichules,[558] keeping near the South Sea mountains all the time, for there are more settlements and a food supply, for it would be suicide to launch out on to the plains country, because it is so vast and is barren of anything to eat, although, it is true, there would not be much need of this after coming to the cows. This is
- 74. only when onegoes in search of Quivira, and of the villages which were described by the Indian called Turk, for the army of Francisco Vazquez Coronado went the very farthest way round to get there, since they started from Mexico and went 110 leagues to the west, and then 100 leagues to the northeast, and 250 to the north, and all this brought them as far as the ravines where the cows were, and after travelling 850 leagues they were not more than 400 leagues distant from Mexico by a direct route. If one desires to go to the country of Tiguex, so as to turn from there toward the west in search of the country of India, he ought to follow the road taken by the army, for there is no other, even if one wished to go by a different way, because the arm of the sea which reaches into this coast toward the north does not leave room for any. But what might be done is to have a fleet and cross this gulf and disembark in the neighborhood of the Island of Negroes[559] and enter the country from there, crossing the mountain chains in search of the country from which the people at Tiguex came, or other peoples of the same sort. As for entering from the country of Florida and from the North Sea, it has already been observed that the many expeditions which have been undertaken from that side have been unfortunate and not very successful, because that part of the country is full of bogs and poisonous fruits, barren, and the very worst country that is warmed by the sun. But they might disembark after passing the river of the Holy Spirit, as Don Hernando de Soto did. Nevertheless, despite the fact that I underwent much labor, I still think that the way I went to that country is the best. There ought to be river courses, because the necessary supplies can be carried on these more easily in large quantities. Horses are the most necessary things in the new countries, and they frighten the enemy most.... Artillery is also much feared by those who do not know how to use it. A piece of heavy artillery would be very good for settlements like those which Francisco Vazquez Coronado discovered, in order to knock them down, because he had nothing but some small machines for slinging and nobody skilful enough to make a catapult or some other machine which would frighten them, which is very necessary.[560]
- 75. I say, then,that with what we now know about the trend of the coast of the South Sea, which has been followed by the ships which explored the western part, and what is known of the North Sea toward Norway, the coast of which extends up from Florida, those who now go to discover the country which Francisco Vasquez entered, and reach the country of Cibola or of Tiguex, will know the direction in which they ought to go in order to discover the true direction of the country which the Marquis of the Valley, Don Hernando Cortes, tried to find, following the direction of the gulf of the Firebrand (Tizon) River.[561] This will suffice for the conclusion of our narrative. Everything else rests on the powerful Lord of all things, God Omnipotent, who knows how and when these lands will be discovered and for whom He has guarded this good fortune. Laus Deo. Finished copying, Saturday the 26th of October, 1596, in Seville.
- 76.
- 77. Aays, not tobe confounded with Ayas, 225 n.; Moscoso at, 243; Indians of, give battle, 243. See also Ayas. Açamor, mentioned, 126. Acaxes, Indians of Culiacan, 345. Acela, town of, 155. Acha, see Picuris. Achese, cacique of, addresses De Soto, 166-167. Acochis, Indian name for gold, 314, 337 n., 342. Acoma, identification of Acuco with, 311 n.; visit of Alvarado to, 311; description of, 311-312; visited by Arellano, 316; route to, 316; mentioned, 358; worship of cross at, 384. Acoma Indians, water supply of, 312. Acosta, Maria de, wife of Pedro Castañeda, 276. Acoste, cacique of, comes to De Soto, 180. Acubadaos Indians, 87. Acuco, see Acoma. Adai Indians, 76 n.
- 78. Adobe, making of,described, 352. Aguacay, mentioned, 237; Moscoso at, 238. Aguar, Indian deity, 118. Aguas Calientes, pueblos of, 359; identification of, 359 n. Aguenes Indians, 84, 85. Alabama, 183 n. Alaniz, Hieronymo, notary, with Narvaez, 22; objects to abandonment of ships, 23; death of, 57. Alarcon, Diego de, confusion of, with Alcaraz, 324 n. Alarcon, Hernando de, expedition of by sea, 294; narrative of, 279, 294 n.; message of, found by Diaz, 303. Alarcon, Pedro de, 294 n. Albino, Indian, 332 n. Alcaraz, Diego de, meeting with Cabeza de Vaca, 112-113; his need of food, 113; returns from incursion, 119; lieutenant of Diaz, 303, 324; inefficiency of, 326; death of, 371.
- 79. Aleman, Juan, namegiven Indian of Tiguex, 317, 321. Alimamos, overtakes De Soto, 177. Alimamu, an Indian chief, 195, 200. Alligators, do harm to Indians, 143; in rivers of New Galicia, 378. Almirantazgo, or Isle of Negroes, 386 n. Altamaca, see Altamaha. Altamaha, 167 n. Altamaha River, 167 n. Alvarado, Hernando de, appointed captain, 293; protects Coronado at Cibola, 301; expedition of, to Rio Grande, 311; report of, 279, 311 n.; visits Acoma, 311; imprisons Pecos chiefs, 315; route of, 316 n.; at Braba, 341. Alvarado, Pedro de, expedition of, to Peru, 288; deeds of, 380. Alvarez, death of, 6. Amaye, Moscoso at, 238. Aminoya, Spaniards hear of, 248; take quarters at, 249; brigantines built at, 250.
- 80. Amushungkwa, a Jemezpueblo, 359 n. Anagados Indians, 71 n. Anane, a fruit, 140. Añasco, Juan de, 135; sent by De Soto to explore harbor in Florida, 145; goes to Espiritu Santo, 162; sent in quest of habitations, 171; finds a town twelve leagues off, 171; makes road through the woods, 172; sent on a reconnoissance, 200, 228, 229; advises Moscoso to put out to sea, 260; and does so with him, 261; meets with opposition from those with him, 261-262; again advises putting out to sea, 264. Anguille River, 215 n. Anhayca Apalache, De Soto at, 161, 162, 164. Anhocan, Cabeza de Vaca at, 116. Anilco, 227, 228, 245, 248, 249. See also Nilco. Animals, of Apalachen, 29; of Florida, mentioned by the Gentleman of Elvas, 271-272. Anoixi, De Soto takes many inhabitants of, 222. Antonio de Santa Maria, Franciscan friar, 288. Antonio Victoria, friar, accident of, 299.
- 81. Welcome to ourwebsite – the perfect destination for book lovers and knowledge seekers. We believe that every book holds a new world, offering opportunities for learning, discovery, and personal growth. That’s why we are dedicated to bringing you a diverse collection of books, ranging from classic literature and specialized publications to self-development guides and children's books. More than just a book-buying platform, we strive to be a bridge connecting you with timeless cultural and intellectual values. With an elegant, user-friendly interface and a smart search system, you can quickly find the books that best suit your interests. Additionally, our special promotions and home delivery services help you save time and fully enjoy the joy of reading. Join us on a journey of knowledge exploration, passion nurturing, and personal growth every day! ebookbell.com